AvePoint Fly is a powerful SaaS solution to support cloud migrations to and between Microsoft 365 tenants. The availability of the public API and PowerShell module adds even more capabilities to support large scale highly automated migrations. In this post we’ll explore how to to prepare for and work with the API and PowerShell cmdlets.
Full disclosure
The company I currently work for is an AvePoint partner and we use their products and services to support our customers. However, AvePoint did not have any saying in the contents of this post prior to publication.
Furthermore, this post relates to the SaaS Fly product as there also is a self-hosted Fly Server product that focuses on hybrid migrations, even though cloud migrations are also supported.
Finally, this post focuses on the use of the public API and PowerShell module, which may be used as components of an overarching automation solution. The latter is not part of this post. If you are interested in learning more about that, please let me know by contacting me.
Considerations for using the public API
AvePoint Fly has a mature user interface that supports the preparation, execution and reporting of migrations. It can provide comprehensive inventory reports that will help you to gain insights on how to approach a specific cloud migration, e.g. a Microsoft 365 tenant-to-tenant migration, which are more common nowadays.
Depending on the size and scope of such a migration, automation may be an important factor in terms of the following activities:
- Pre-scanning
- Pre-provisioning
- Creating migration projects
- Importing and verifying mappings
- Scheduling/starting migrations
- Monitoring progress
- Reporting.
The public API for AvePoint Fly can help to accommodate automation for some of the key parts of a typical migration process. Pre-provisioning may still be something that is performed separate from the API in many occasions, but the other activities are in the sweet spot of what the API provides.
Especially in large scale migrations, these activities can be time-consuming and potentially error prone. Automating through the public API can help to save time which is always scarce.
Getting started
In order to work with the public API, there are a couple of things to consider:
- Purchasing or creating a certificate for public API authentication
- Registering and configuring an app in AvePoint Online Services
- Installing the Fly.Client PowerShell module from the PowerShell Gallery
- Downloading the mapping file templates for each workload.
Obviously, licenses are also a prerequisite to actually using the Fly capabilities for production purposes, but the mentioned considerations work within the Fly trail-period.
Getting the certificate
The public API works with a certificate for authentication. This can be a self-signed certificate or, highly recommended for production purposes, a commercial certificate.
The certificate is stored in the personal certificate store on the Windows Server that will host the PowerShell scripting to interact with the API. The private key should be exportable. The AOS portal requires uploading the cer-file of the certificate.
Registering an app
The AvePoint Online Services (AOS) API’s work, to some extend, in a similar way as the Microsoft Graph. So first step is to register an app in the AOS-portal using the following URL or via “Administration > App registrations”:
https://www.avepointonlineservices.com/app/registration/index
You can choose “Create” to register a new app.
Provide a name for the app registration, e.g. “Fly Migration”.
Next, choose the intended permissions for the app; fly.graph.readwrite.all.
Finally, upload the certificate. Be sure to copy the thumbprint to a temporary text file for later use. Save the registration to complete the process. Revisit the app registration to also copy the Application (Client) ID.
Connecting to the API
Working with the Fly API, requires the use of the Fly.Client PowerShell module, which can be downloaded from the PowerShell Gallery through the following cmdlet:
Install-Module -Name 'Fly.Client' -Scope 'AllUsers'
The module comes with a set of cmdlets that can be used for automation. For a complete reference, there is a public Github project.
To connect to AvePoint Fly through the public API, use the following cmdlet, using the previously copied client ID and certificate thumbprint:
$url = 'https://graph-we.avepointonlineservices.com/fly'
$clientId = '{Application (Client) ID}'
$cert = Get-ChildItem -Path 'Cert:\CurrentUser\My\{certificate thumbprint}'
Connect-Fly -Url $url -ClientId $clientId -Certificate $cert
If the app registration was properly configured, the cmdlet will not return any response. If not, an error message will be shown indicating a misconfiguration or certificate problem.
From this point onwards, you can start to create projects, perform pre-scans and mapping validations, start or schedule migrations, monitor and download (error)reports.
These activities can be performed with the module, where specific cmdlets are provided for specific workloads like Microsoft Teams, OneDrive for Business, SharePoint Online and Exchange Online.
Connections, policies and user mappings
Where the cmdlets focus on repetitive activities, there are still some manual prerequisite configurations to be performed for Fly in the AOS portal. this includes the following:
- Creating app (and service account) connections in the source and destination tenants
- Configuring migration policies for each workload
- Configuring or importing user/group mappings.
Please note that the links, apart from the first one, directs to Microsoft Teams guidance on that topic. This is intended as the remainder of this post will focus on using the public API for preparing and performing migrations for this workload.
Microsoft Teams
Once the prerequisite configurations are completed, you can create a new project via the PowerShell module:
New-FlyMigrationProject `
-Name 'Teams - department 1'`
-SourceConnection 'Microsoft Teams - Contoso' `
-DestinationConnection 'Microsoft Teams - AdventureWorks' `
-Policy 'Teams - General'
The cmdlet requires a descriptive name and the exact names for the connections and migration policy for the Microsoft Teams Workload.
Importing mappings
After creating the project, you can import the mappings via a populated mapping template file specific to the workload.
Import-FlyTeamsMappings `
-Project 'Teams - department 1' `
-Path 'C:\Temp\Fly_Microsoft_Teams_Add_Mapping.csv'
Preflight checks
Once all mappings are imported, the verification can be performed to ensure that the mappings exist or to rule out that existing teams objects are encountered.
Start-FlyTeamsVerification `
-Project 'Teams - department 1'
The result of the verification can be reviewed in the portal.
To ensure a smooth migration, pre-scanning can also be performed using the public API. This is highly recommended to rule out any blocking issues prior to the migration
Start-FlyTeamsPreScan `
-Project 'Teams - department 1'
Similar to the verification, the result of the pre-scan can be reviewed or downloaded from the portal or by using the following cmdlet:
Export-FlyTeamsMappingStatus `
-Project 'Teams - department 1'`
-OutFile 'C:\Temp\Mappings\Fly_Microsoft_Teams_Mapping_Status.csv'
Start or schedule the migration
Once all preflight checks are completed, the migration can be started. The cmdlet can be configured to start instantly.
Start-FlyTeamsMigration `
-Project 'Teams - department 1' `
-Mode 'FullMigration'
Or by adding the ‘ScheduleTime’ parameter to ensure that the migration starts at a specific date and time.
-ScheduleTime (Get-Date -Date "2023-08-05 19:00:00").ToUniversalTime()
Monitoring
During the migration, you can download the mapping status to gain insights on (pre-)migration progress (Started, Completed, Finished with warnings or errors, etc.) with the previously mentioned ‘Export-FlyTeamsMappingStatus’ cmdlet.
Reporting
When the migration has completed, you can use the following cmdlet to download the detailed reports. Using the “FileType” parameter, you can choose “Excel” or “CSV”-formats.
Export-FlyTeamsMigrationReport `
-Project 'Teams - department 1' `
-OutFolder 'C:\Temp\Reports' `
-FileType 'CSV'
Conclusions
The public API is fairly new. With each new release additional capabilities are made available through the PowerShell module. Since the August 2023 release, it is possible to perform the activities as seen in the Microsoft Teams example for SharePoint Online, OneDrive for Business and Exchange Online. So the typical workloads are present and working.
I will be keeping track of the public API to see what improvements are made in the future. In the meanwhile, I will be working on integrating the PowerShell module in the automation solutions I created and maintain.
