Release 4.1.0

Author: drache42

examples/Csharp.ExampleApplication/Hooks/Transformers/SimpleScheduleStartAtTransformer.cs

@@ -0,0 +1,50 @@
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using Tableau.Migration.Content.Schedules;
+using Tableau.Migration.Content.Schedules.Cloud;
+using Tableau.Migration.Engine.Hooks.Transformers;
+using Tableau.Migration.Resources;
+
+namespace Csharp.ExampleApplication.Hooks.Transformers
+{
+    #region class
+    public class SimpleScheduleStartAtTransformer<T> 
+        : ContentTransformerBase<T> 
+        where T : IWithSchedule<ICloudSchedule>
+    {
+        private readonly ILogger<IContentTransformer<T>>? _logger;
+
+        public SimpleScheduleStartAtTransformer(
+            ISharedResourcesLocalizer localizer, 
+            ILogger<IContentTransformer<T>> logger) 
+            : base(
+                  localizer, 
+                  logger)
+        {
+            _logger = logger;
+        }
+
+        public override async Task<T?> TransformAsync(
+            T itemToTransform, 
+            CancellationToken cancel)
+        {
+            // In this example, the `Start At` time is in the UTC time zone.
+            if (itemToTransform.Schedule.FrequencyDetails.StartAt is not null)
+            {
+                // A simple conversion to the EDT time zone.
+                var updatedStartAt = itemToTransform.Schedule.FrequencyDetails.StartAt.Value.AddHours(-4);
+
+                _logger?.LogInformation(
+                    @"Adjusting the 'Start At' from {previousStartAt} to {updatedStartAt}.",
+                    itemToTransform.Schedule.FrequencyDetails.StartAt.Value,
+                    updatedStartAt);
+
+                itemToTransform.Schedule.FrequencyDetails.StartAt = updatedStartAt;
+            }
+
+            return await Task.FromResult(itemToTransform);
+        }
+    }
+    #endregion
+}

examples/Python.ExampleApplication/Hooks/transformers/schedule_startat_transformer.py

@@ -0,0 +1,15 @@
+from datetime import time
+from tableau_migration import (
+    ContentTransformerBase,
+    ICloudExtractRefreshTask
+)
+
+class SimpleScheduleStartAtTransformer(ContentTransformerBase[ICloudExtractRefreshTask]):
+    def transform(self, itemToTransform: ICloudExtractRefreshTask) -> ICloudExtractRefreshTask:
+        # In this example, the `Start At` time is in the UTC time zone.
+        if itemToTransform.schedule.frequency_details.start_at:
+            prev_start_at = itemToTransform.schedule.frequency_details.start_at
+            # A simple conversion to the EDT time zone.
+            itemToTransform.schedule.frequency_details.start_at = time(prev_start_at.hour - 4, prev_start_at.minute, prev_start_at.second, prev_start_at.microsecond);
+        
+        return itemToTransform

src/Documentation/articles/configuration/basic.md

@@ -0,0 +1,40 @@
+# Basic Configuration
+
+## Migration Plan
+
+The migration plan is a required input in the migration process. It defines the Source and Destination servers and the hooks executed during the migration. Consider the Migration Plan as the steps the Migration SDK follows to migrate the information from a given source to a given destination.
+
+The [`IMigrationPlan`](xref:Tableau.Migration.IMigrationPlan) interface defines the Migration Plan structure. The easiest way to generate a new Migration Plan is using [`MigrationPlanBuilder`](xref:Tableau.Migration.Engine.MigrationPlanBuilder). Following are the steps needed before [building](#build) a new plan:
+
+- [Define the required Source server](#source).
+- [Define the required Destination server](#destination).
+- [Define the required Migration Type](#migration-type).
+
+### Source
+
+ The method [`MigrationPlanBuilder.FromSourceTableauServer`](xref:Tableau.Migration.Engine.MigrationPlanBuilder.FromSourceTableauServer(System.Uri,System.String,System.String,System.String,System.Boolean))  defines the source server by instantiating a new [`TableauSiteConnectionConfiguration`](xref:Tableau.Migration.Api.TableauSiteConnectionConfiguration) with the following parameters:
+
+- **serverUrl**
+- **siteContentUrl:**(optional)
+- **accessTokenName**
+- **accessToken**
+
+### Destination
+
+The method [`MigrationPlanBuilder.ToDestinationTableauCloud`](xref:Tableau.Migration.Engine.MigrationPlanBuilder.ToDestinationTableauCloud(System.Uri,System.String,System.String,System.String,System.Boolean)) defines the destination server by instantiating a new [`TableauSiteConnectionConfiguration`](xref:Tableau.Migration.Api.TableauSiteConnectionConfiguration) with the following parameters:
+
+- **podUrl**
+- **siteContentUrl** The site name on Tableau Cloud.
+- **accessTokenName**
+- **accessToken**
+
+> [!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.
+
+### Migration Type
+
+The method [`MigrationPlanBuilder.ForServerToCloud`](xref:Tableau.Migration.Engine.MigrationPlanBuilder.ForServerToCloud) will define the migration type and load all default hooks for a **Server to Cloud** migration.
+
+### Build
+
+The method [`MigrationPlanBuilder.Build`](xref:Tableau.Migration.Engine.MigrationPlanBuilder.Build) generates a Migration Plan ready to be used as an input to a migration process.

src/Documentation/articles/index.md

@@ -0,0 +1,58 @@
+# Introduction
+
+Welcome to the developer documentation for the Tableau Migration SDK. The Migration SDK is primarily written in C# using the [.NET](https://dotnet.microsoft.com/en-us/learn/dotnet/what-is-dotnet-framework) Framework. It includes a [Python API](~/api-python/index.md) to enable interoperability with Python.
+
+## Supported languages
+
+You can develop your migration application using one of the supported languages
+
+- [Python](https://www.python.org/)
+- C# using the [.NET Framework](https://dotnet.microsoft.com/en-us/learn/dotnet/what-is-dotnet-framework)
+
+## Prerequisites
+
+To develop your application using the [Migration SDK](https://github.com/tableau/tableau-migration-sdk), you should
+
+- Understand framework and language concepts for one of the languages the SDK supports.
+- Be able to design and write applications in one of the supported languages.
+- Understand how to import and use third party packages
+- Understand logging and general troubleshooting of applications.
+
+## Quick Start
+
+- Install a [.NET Runtime](https://dotnet.microsoft.com/en-us/download).
+- Install the Migration SDK
+
+## [Python](#tab/Python)
+
+  Install using PIP
+  - [PIP CLI](https://pip.pypa.io/en/stable/cli/pip_install): `pip install tableau_migration`
+
+## [C#](#tab/CSharp)
+  
+  Install using NuGet
+  - [dotnet CLI](https://learn.microsoft.com/en-us/nuget/quickstart/install-and-use-a-package-using-the-dotnet-cli): `dotnet add package Tableau.Migration`
+  - [Nuget Package Manager](https://learn.microsoft.com/en-us/nuget/quickstart/install-and-use-a-package-in-visual-studio): Search for `Tableau.Migration`.
+
+---
+
+- Use the sample code in one of the [Reference](#getting-started-and-api-reference) sections to get started.
+- Use the [Resource](#resources) sections to further customize your application.
+
+## Getting started and API Reference
+
+- [Python API Reference](~/api-python/index.md) : Getting started sample and the complete Python API Reference for comprehensive documentation.
+- [C# API Reference](~/api-csharp/index.md): Getting started sample and the complete C# API Reference for detailed documentation.
+
+## Resources
+
+- [Articles](~/articles/index.md): Articles covering a range of topics, including customization of the Migration SDK.
+- [Code Samples](~/samples/index.md): Code samples to kickstart your development process.
+
+## Source Code
+
+The Tableau Migration SDK is open source. The source code is in our [GitHub repo](https://github.com/tableau/tableau-migration-sdk).
+
+## Contributing
+
+Refer to this handy [contribution guide](https://github.com/tableau/tableau-migration-sdk/blob/main/CONTRIBUTING.md) if you would like to contribute to the Migration SDK.

src/Documentation/images/configuration.svg

@@ -0,0 +1,7 @@
+# Batch Migration Completed
+
+Batch Migration Completed Hooks allow custom logic to run when a migration batch completes.
+
+The following samples cover some common scenarios:
+
+- [Sample: Migration batch logging](~/samples/batch-migration-completed/log_migration_batches.md)

src/Documentation/images/hooks.svg

@@ -0,0 +1,7 @@
+# Bulk Post-Publish Hooks
+
+Bulk post-publish hooks allow you to update content item batches after they are migrated to the destination.
+
+The following samples cover some common scenarios:
+
+- [Sample: Bulk logging](~/samples/bulk-post-publish/bulk_logging.md)

src/Documentation/samples/batch-migration-completed/index.md

@@ -0,0 +1,12 @@
+# Filters
+
+Filters allow you to skip migrating certain content items.
+
+> [!Note]
+> Filters do not have a cascading effect. You will need to write similar filters for the related content items as well.
+
+The following samples cover some common scenarios:
+
+- [Sample: Filter projects by name](~/samples/filters/filter_projects_by_name.md)
+
+- [Sample: Filter users by site role](~/samples/filters/filter_users_by_site_role.md)

src/Documentation/samples/bulk-post-publish/index.md

@@ -0,0 +1,48 @@
+# Code Samples
+
+Once you have started building your migration using the example code in [C#](~/api-csharp/index.md) or [Python](~/api-python/index.md), you may want to further customize your migration using hooks. This section provides code samples to assist you.
+
+[Learn more about hooks here.](~/articles/hooks/index.md)
+
+## Hook Registration
+
+To use hooks, you need to register them with the [plan builder](~/articles/configuration.md#migration-plan).
+
+The process of registering hooks differs slightly between C# and Python, as described below.
+
+# [Python](#tab/Python)
+
+In Python, injecting an object into the class constructor is not supported, and in most cases, it is unnecessary.
+
+To register a Python hook object, simply create the object and add it to the appropriate hook type collection.
+
+**Generic Form:** `plan_builder.[hook type collection].add([hook object])`
+
+**Example:** 
+```
+plan_builder.filters.add(UnlicensedUsersFilter)
+```
+
+# [C#](#tab/CSharp)
+
+In C#, the hook object should be registered with Dependency Injection (DI). This allows hooks to have any object injected into the constructor without concern for the source of the object.
+
+Learn more about [dependency injection](~/articles/dependency_injection.md).
+
+To register your hook object with the dependency injection service provider, simply add it.
+
+**Generic Form:** `services.AddScoped<[Object type]>();`
+
+**Example:**
+```
+services.AddScoped<UnlicensedUsersFilter>();
+```
+
+Once the hook is registered with DI, it must be added to the appropriate [hook collection](~/articles/hooks/custom_hooks.md).
+
+**Generic Form:** `_planBuilder.[hook type collection].Add<[object name], [hook type]>();`
+
+**Example:**
+```
+_planBuilder.Filters.Add<UnlicensedUsersFilter, IUser>();
+```