Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Scotm copy edits sig #14

Merged
merged 2 commits into from
Nov 29, 2024
Merged

Scotm copy edits sig #14

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e730daf
w-17263309: Proposed copy edits.
smarvin Nov 18, 2024
15b1746
w-17263309: signing commit
smarvin Nov 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 64 additions & 61 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,38 @@
# Tableau Migration App
### Table of Contents

- [Tableau Migration App](#tableau-migration-app)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Usage](#usage)
- [Tableau Server and Cloud URLs](#tableau-server-and-cloud-urls)
- [Personal Access Tokens](#personal-access-tokens)
- [User Mappings](#user-mappings)
- [Username Already in Email format](#username-already-in-email-format)
- [User has an Associated Email](#user-has-an-associated-email)
- [Default Domain Mapping](#default-domain-mapping)
- [CSV Mapping](#csv-mapping)
- [Outputs](#outputs)
- [Logging](#logging)
- [FAQ](#faq)
- [The application is taking a long time, is it stuck?!](#the-application-is-taking-a-long-time-is-it-stuck)
- [How do I migrate items with more specific logic rules?](#how-do-i-migrate-items-with-more-specific-logic-rules)
- [How do I exclude certain items from being migrated?](#how-do-i-exclude-certain-items-from-being-migrated)
- [What order will my resources get migrated in?](#what-order-will-my-resources-get-migrated-in)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Usage](#usage)
- [Tableau Server and Cloud URLs](#tableau-server-and-cloud-urls)
- [Personal Access Tokens](#personal-access-tokens)
- [User Mappings](#user-mappings)
- [Username already in email format](#username-already-in-email-format)
- [User has an associated email](#user-has-an-associated-email)
- [Default Domain Mapping](#default-domain-mapping)
- [CSV Mapping](#csv-mapping)
- [Outputs](#outputs)
- [Logging](#logging)
- [Canceling a Migration](#canceling-a-migration)
- [Resuming a Migration](#resuming-a-migration)
- [FAQ](#faq)
- [The application is taking a long time, is it stuck?!](#the-application-is-taking-a-long-time-is-it-stuck)
- [How do I migrate items with more specific logic rules?](#how-do-i-migrate-items-with-more-specific-logic-rules)
- [How do I exclude certain items from being migrated?](#how-do-i-exclude-certain-items-from-being-migrated)
- [What order will my resources get migrated in?](#what-order-will-my-resources-get-migrated-in)

## Features
**The Tableau Migration App can be downloaded from the [releases](https://github.com/tableau/tableau-migration-app/releases) page of this repo.**
**You can download the Tableau Migration App from the [releases](https://github.com/tableau/tableau-migration-app/releases) page of this repo.**

The purpose of the Tableau Migration App is to provide users with a method to perform simple migrations from their Tableau Server to Tableau Cloud. This app is meant to accompany the [Tableau Manual Migration Guide](https://help.tableau.com/current/guides/migration/en-us/emg_intro.htm) and replace the work required for the migration steps.

<div align="center">
<img src="/screenshots/TableauMigrationApp.png" alt="Tableau Migration App" width=400>
</div>

* The migration app uses the [Tableau Migration SDK](https://github.com/tableau/tableau-migration-sdk) under the hood, and supports all migration resources that the SDK offers.
* At the time of this writing, this includes:
* The migration app uses the [Tableau Migration SDK](https://github.com/tableau/tableau-migration-sdk) under the hood, and supports all migration resources that the Migration SDK offers.
* The Migration SDK currently includes:
* Users
* Groups
* Projects
Expand All @@ -46,64 +49,64 @@ The purpose of the Tableau Migration App is to provide users with a method to pe
> <div align="center"><img src="/screenshots/UrlParams.png" alt="Tableau Migration App URL Fields" ></div>
The fields in this section are for providing the URIs of the Tableau Server you wish to migrate from, and the Tableau Cloud you wish to migrate to.

These URIs can be found from your browser address bar when logging into the respective Tableau products, or is what you use when connecting from Tableau Desktop.
These URIs can be found in your browser address bar when logging into the respective Tableau products, or are what you use when connecting from Tableau Desktop.

> The `Base URI` and `Site Name` fields will automatically extract the appropriate information based on the URI provided. Double check that these are correct before moving forward.
> The `Base URI` and `Site Name` fields will automatically extract the appropriate information based on the URI provided. Double check that these are correct before continuing.

**Note**: Multi-site environments will show the `/site/` as part of the URI. If yours does not have one, it is not a problem, and just means that you only have a single site; the `Default` site.
**Note**: Multi-site environments show the `/site/` as part of the URI. If yours doesn’t have one, it isn’t a problem, and just means that you only have a single site; the `Default` site.

### Personal Access Tokens
> <div align="center"><img src="/screenshots/PatParams.png" alt="Tableau Migration App Token Fields" ></div>

Personal Access Tokens (PATs) are used by the app to programmatically access and make changes to the corresponding Tableau Products.

PATs can be generated in your Tableau Environment by going to

> Users > {Your User Here} > Settings > Personal Access Tokens

Where you will be prompted to provide a `Token name` and a `Create Token` button.
> <div align="center"><img src="/screenshots/CreatePAT.png" alt="Tableau Migration PAT" ></div>
The app uses personal access tokens (PATs) to programmatically access and make changes to the corresponding Tableau products.

To generate PATs in your Tableau Environment:

Once created, a `secret` will be provided to you for that PAT.
1. Go to **Users > {Your User Here} > Settings > Personal Access Tokens**.
2. Provide a **Token name**.
3. Click the **Create Token** button.
> <div align="center"><img src="/screenshots/CreatePAT.png" alt="Tableau Migration PAT" ></div>
4. After it’s created, a `secret` will be displayed to you for that PAT. Click **Copy Secret**.

> <div align="center"><img src="/screenshots/CreatePATDetails.png" alt="Tableau PAT Details" ></div>
> <div align="center"><img src="/screenshots/CreatePATDetails.png" alt="Tableau PAT Details" ></div>

The `Token Name` is to be filled in the `PAT Name` field of the Migration app, and the `Secret` goes in the `PAT` field.
5. In the Migration app:
1. Enter the **Token Name** in the **PAT Name** field.
2. Enter the **Secret** that you copied earlier in the **PAT** field.

This will need to be done separately for both the source Tableau Server and the destination Tableau Cloud. Each PAT only provides access to the system it was geneated on.
This needs to be done separately for both the source Tableau Server and the destination Tableau Cloud. Each PAT only provides access to the system it was generated on.

**Note** The PAT will only provide access to resources of which the user is authorized to have. Resources of which the PAT owner does not have access to will **not** be migrated.
**Note** The PAT only provides access to resources the user is authorized to have. Resources that the PAT owner doesn’t have access to will **not** be migrated.

### User Mappings
> **!Important!** Users in Tableau Cloud must have a username in the form of an email. Since Tableau Server does not have this restriction, we've provided different ways for you to designate how the users should be migrated if they don't currently follow this format. The different cases are detailed below.
> **!Important!** Users in Tableau Cloud must have a username in the form of an email. Because Tableau Server doesn’t have this restriction, we've provided different ways for you to designate how the users should be migrated if they don't currently follow this format. The different cases are detailed below.

The order of priority of defined mappings for the migration are as such:
1. CSV Defined mapping
The order of priority of defined mappings for the migration are:
1. CSV-defined mapping
2. Username already in email format
3. User has an associated Email
4. Default Domain Mapping
3. User has an associated email
4. Default domain mapping

Meaning that if a defined mapping is found for a user in the CSV file, that mapping will be used even if the user has an associated email.
This means that if a defined mapping is found for a user in the CSV file, that mapping is used even if the user has an associated email.

The following sections will detail more about each mapping option.
The following sections detail more about each mapping option.

#### Username Already in Email format
If a username is already in an email format, then nothing will need to be done and the User will be migrated over as is.
#### Username already in email format
If a username is already in an email format, then nothing needs to be done and the user will be migrated over as is.

#### User has an Associated Email
#### User has an associated email
If a user has an associated email set to the profile, that email will instead be used for the user when migrating.

#### Default Domain Mapping
> <div align="center"><img src="/screenshots/DefaultDomainMapping.png" alt="Tableau Migration App Token Fields" ></div>

We also provide a default domain mapping. When this is done, all users will have their names appended with that domain to create an email.

e.g. If a User with username `PeterP` is to be migrated, and the `Default User Domain` is set to `DailyBugle.com`, then that user will be migrated to Tableau Cloud as `[email protected]`
For example, if a user with username `PeterP` is to be migrated, and the `Default User Domain` is set to `DailyBugle.com`, then that user will be migrated to Tableau Cloud as `[email protected]`

This option can be disabled by clicking the checkbox. In which case, users that do not have a mapping found from the other options will **not** be migrated to Tableau Cloud.
This option can be disabled by clicking the checkbox. In this case, users that don’t have a mapping found from the other options will **not** be migrated to Tableau Cloud.

**Note** Users containing illegal email characters in their usernames will still fail migration even with a default domain mapped. For example `[][email protected]` is not a valid username for Tableau Cloud.
**Note** Users containing illegal email characters in their usernames will still fail migration even with a default domain mapped. For example `[][email protected]` isn’t a valid username for Tableau Cloud.

**Note2** Users with a space in their Tableau Server usernames such as `Renee Montoya` will have their spaces replaced with a `.` instead, becoming `[email protected]`.

Expand All @@ -113,11 +116,11 @@ For more fine-grained control over how individual users are migrated, you can de

To do so, the file should contain one user mapping per line, separated by a comma (`,`).

i.e. Every line should look like: `{TableauServerUserName},{TableauCloudUsername}`
That is, every line should look like: `{TableauServerUserName},{TableauCloudUsername}`

The `{TableauServerUserName}` **MUST** match the username exactly and is **case sensitive**. Or else the user will not be mapped.
The `{TableauServerUserName}` **MUST** match the username exactly and is **case-sensitive** or else the user will not be mapped.

Here is an example of what the file format should be like.
Here’s an example of the proper file format:

<div style="border: 1px solid #000; padding: 10px; border-radius: 8px;">

Expand All @@ -131,26 +134,26 @@ Leonardo, [email protected]
</div>
<br />

**Note** Starting and trailing white spaces will be trimmed. `user1 , [email protected]` is the same as `user1,[email protected]` for the sake of legibility.
**Note** Starting and trailing white spaces are trimmed. `user1 , [email protected]` is the same as `user1,[email protected]` for the sake of legibility.

### Outputs
Ongoing outputs of the running Migration will be shown in the output window.
> <div align="center"><img src="/screenshots/OutputWindow.png" alt="Tableau Migration App Output" width=400 ></div>

Once migration of a resource is completed, whether successful or not, an associated message will show in the window.
After migration of a resource is completed, whether successful or not, an associated message shows in the window.

> <div align="center"><img src="/screenshots/OutputWindowFilled.png" alt="Tableau Migration App Output" width=400 ></div>
### Logging
Application logs can be found in the `Logs` folder from where the application is run. These logs contain all the REST requests made by the underlying [Tableau Migration SDK](https://github.com/tableau/tableau-migration-sdk) to the Tableau environments to perform the migration.

These logs can be used to provide further insight to the ongoing status and/or errors of the migration.

### Cancelling a Migration
When a migration is running, a `Cancel Migration` button will appear. If you want to stop the current migration, you can click this button. Doing so will also present you with a dialog window to save a manifest file.
### Canceling a Migration
When a migration is running, a **Cancel Migration** button appears. If you want to stop the current migration, you can click this button. Doing so will also present you with a dialog window to save a manifest file.

> <div align="center"><img src="/screenshots/SaveManifest.png" alt="Tableau Migration App Save Manifest" width=400 ></div>

This manifest can be used to Resume a migration at a later time and continue where you left off.
This manifest can be used to resume a migration later and continue where you left off.

### Resuming a Migration
If you have a manifest file saved from a previous run, you can resume a migration by selecting the dropdown arrow on the right side of the `Start Migration` button and selecting `Resume Migration`.
Expand All @@ -161,15 +164,15 @@ If you have a manifest file saved from a previous run, you can resume a migratio
### FAQ

#### The application is taking a long time, is it stuck?!
> Check the logs. It could be that the current resource is really large and is taking a long time to migrate.
> Check the logs. It could be that the current resource is large and is taking a long time to migrate.
>
> Or that the application has hit its limit on the number of requests it can make in the current time frame, and is currently waiting until it can send more. In this case, the logs messages should mention how much longer it needs to wait for.
> Or it could be that the application has hit its limit on the number of requests it can make in the current time frame, and is waiting until it can send more. In this case, the logs messages should mention how much longer it needs to wait for.

#### How do I migrate items with more specific logic rules?
> If you want finer control over how migration is handled, such as renaming resources or applying special rules such as re-assigning resources, then it is recommended that you use the [Tableau Migration SDK](https://github.com/tableau/tableau-migration-sdk) to programmatically perform the migration.
> If you want finer control over how the migration is handled, such as renaming resources or applying special rules like reassigning resources, then we recommend that you use the [Tableau Migration SDK](https://github.com/tableau/tableau-migration-sdk) to programmatically perform the migration.

#### How do I exclude certain items from being migrated?
> You can either delete the items after the migration is performed, or you will have to use the [Tableau Migration SDK](https://github.com/tableau/tableau-migration-sdk)
> You can either delete the items after the migration is performed, or you’ll have to use the [Tableau Migration SDK](https://github.com/tableau/tableau-migration-sdk)

#### What order will my resources get migrated in?
> Resources are first sorted from largest to smallest, and migrated in that order.