Connecting with the BT PowerShell module requires an API key generated by an authorized client administrator in Power365.
Only an authorized Client Administrator can manage API keys in Power365.
Only a Power365 user with the Client Administrator Role can manage API keys.
To generate a new API key as the Client Administrator:
- Log in to Power365.
- Select API Tokens from the Manage section of the top left menu.
- Click New to create a new key.
- Follow the prompts.
- Give the key a Name.
- Select a Role (Read, Write).
- Select an Expiration date.
- Copy and save the key.
Best practice is to create a new key for each different user needed.
Note: The key is only available to copy during the key creation process. If that key copy is subsequently lost, it will be necessary to create a new key.
Only a Power365 user with the Client Administrator Role can manage API keys.
There are two options for handling old API keys: Delete them or Change their Expiration date.
Keys with Expiration dates set to the current date or prior are immediately disabled.
- Log in to Power365.
- Select API Tokens from the Manage section of the top left menu.
- To Delete a key click on the DELETE action on that key’s row in the API Keys table. When prompted, confirm the deletion.
- Alternatively, to change the Expiration date of a key enter a new date in the Expires column for that key’s row in the API Keys table.
The PowerShell module is a library of PowerShell language commands that let you manage your Power365 data. Here are some common examples of operations you can perform with the PowerShell module:
- Manage multiple clients, projects, profiles and more
- Get user status and statistics
- Start actions and monitor progress
- Create and manage migration waves
- Retrieve job history and download logs
PowerShell 5.1 (recommended)
.Net 4.7.2 or above
An access token issued by an authorized client administrator
Only an authorized Client Administrator can manage API keys in Power365. See API Tokens for steps.
Download and install the module by invoking the following from PowerShell:
Install-Module BinaryTree.Power365 -Force |
Verify the installed PowerShell module by running the following command and inspecting the output:
Get-InstalledModule -Name BinaryTree.Power365 | FL |
To verify your installed version against the latest version in PSGallery, run the following then compare the results.
# Get module version from PSGallery |
Find-Module BinaryTree.Power365 | select version |
# Get installed module version |
Get-InstalledModule BinaryTree.Power365 | select version |
To connect to Power365 using PowerShell, you will need an API key generated from within Power365. Once you have an API key then run the following:
$apiKey = "<API Key>" |
Connect-BTSession -ApiKey (ConvertTo-SecureString $apiKey -AsPlainText -Force) |
See also ‘How do I get a new API key?’ below.
Help is only a command away. Each module has a help file to keep you updated on the latest cmdlet functions and properties.
# Get a list of Binary Tree cmdlets |
Get-Help *-BT* | select name, synopsis |
# Get list of installed cmdlets and their parameters |
Get-Command -Module BinaryTree.Power365 | select name, ParameterSets |
# Get detailed help from a single cmdlet |
Get-Help <command name> -Detailed |
Yes, the BT PowerShell module requires existing access to a Power365 client.
Yes, connecting with the BT PowerShell module requires an API key generated by an authorized client administrator in Power365. See API Tokens for more information.
After successfully connecting to Power365 you can run the Get-BTSession cmdlet to view more information about the current session.
Yes, you can use the Set-BTProject cmdlet to manage which client session is being used in the current PowerShell context.
To view a list of projects in your current session use the Get-BTProject cmdlet with no parameters.
To retrieve a subset of projects with the Get-BTProject cmdlet you can use the –Filter parameter with an OPath syntax string to search the ProjectName, ProjectID, or ProjectType. Options include –eq, -like, -lt, -gt, and * for wildcard.
# This command returns Projects whose ProjectName begins with 'M' |
Get-BTProject -Filter "ProjectName -like 'M*'” |
This operation is currently under construction and only available through the Power365 UI.
To set the migration profile on a User you can run Set-BTUser with the –Profile parameter defined.
# Example of setting a User’s Migration Profile |
Set-BTUser -Identity bob.smith@contoso.com -Profile 'My Profile' |
To create a new Wave run the following:
# Example of creating a new Wave |
New-BTWave -WaveName 'My Wave Name' -Project <projectID> |
A User can only be in one Wave at a time. To move a User to a different Wave use the Set-BTUser cmdlet. To clear a User’s Wave use the –Wave parameter $null.
# Example of setting a User's Wave |
Set-BTUser –Identity bob.smith@contoso.com –Wave "My Wave Name” |
# Example of clearing a User's Wave |
Set-BTUser –Identity bob.smith@contoso.com –Wave $null |
To retrieve a subset of environments with the Get-BTEnvironment cmdlet you can use the –Filter parameter with an OPath syntax string to search the TenantName, TenantGUID, or any supported filter attributes. Options include –eq, -like, -lt, -gt, and * for wildcard.
# This command returns Environment with TenantName equal to “BTCloud1” |
Get-BTEnvironment -Filter "TenantName -eq 'BTCloud1'" |
To set discovery frequency for an environment, run Set-BTEnvironment with the -DiscoveryFrequencyHours parameter defined.
# This command set the discovery frequency to 12 hours for “BTCloud1” environment. |
Set-BTEnvironment -Identity 'BTCloud1' -DiscoveryFrequencyHours 12 |
# This command set the discovery frequency to 12 hours for all environments. |
Get-BTEnvironment | Set-BTEnvironment -DiscoveryFrequencyHours 12 |
To start the discovery process for an environment, run Start-BTDiscovery cmdlet. Optional parameter – DiscoveryDeltaTimestamp can be used to perform delta discovery to query all changes committed in the tenant after the date-time defined.
# This command starts discovery process for an environment with TenantName equal to “BTCloud1”. |
Get-BTEnvironment -Filter "TenantName -eq 'BTCloud1'" | Start-BTDiscovery |
# This command starts discovery process with an optional “DiscoveryDeltaTimestamp” parameter defined for an environment with TenantID equal to ‘1869’ |
Start-BTDiscovery -Identity 1869 -DiscoveryDeltaTimestamp "6/17/2020 4:45:46 PM" |
To get a full list of User properties run the Get-BTUser cmdlet and specify the -Identity of the User whose properties you would like to retrieve.
# Example of retrieving User properties |
Get-BTUser –Identity ‘Bob Smith’ |
Target User properties are retrieved the same way as source User properties. Note that if the User has been matched then the source and target properties are returned as one record.
# Example of retrieving User properties |
Get-BTUser –Identity ‘Bob Smith’ |
To view User properties by Wave run the Get-BTUser cmdlet with the -Wave parameter specifying the Wave in question:
# Example of retrieving User properties by Wave |
Get-BTUser -Wave ‘1234’ |
To set a Match on a User run Set-BTUser with the -MatchIdentity parameter defined to set the User's matching target object. To instead clear the Match on a User run with a –MatchIdentity parameter value of $null.
# Example of setting a User Match |
Set-BTUser -Identity bob.smith@contoso.com -MatchIdentity bob.smith@fabrikam.com |
# Example of clearing a User Match |
Set-BTUser -Identity bob.smith@contoso.com -MatchIdentity $null |
To set multiple Users’ Matches at once run the Set-BTUser cmdlet with the -MatchProperty parameter. The easiest way to do this is by directing a csv file containing the source User identities and their corresponding target identities into the command with a pipe.
# Example of setting multiple Users' Matches based on an input file |
Import-Csv <InputFilePath> | Set-BTUser -MatchProperty TargetUserPrincipalName |
The action cmdlets which can be run to start an action for a particular User are: Start-BTCutover, Start-BTPrepare, and Start-BTSync. Run them with the –User parameter and specify a User id, identity, or object.
# Example of starting a User Action |
Start-BTCutover -User bob.smith@contoso.com |
This operation is under construction and currently only available in the Power365 UI.
The Get-BTLog cmdlet can return Sync, Prepare, Cutover or Discovery Logs depending on which Action job ID is passed to it. In this regard it will often be paired with the Get-BTSync, Get-BTPrepare, Get-BTCutover and Get-BTEnvironment cmdlets for retrieving the desired Action job ID(s).
When you want a single User Log rather than all of them it can be helpful to insert a Select-Object clause with a –First or –Last parameter. To get only a User’s last Sync Log use a combination of the Get-BTUser, Get-BTSync, and Get-BTLog cmdlets similar to the following:
# Example of getting a User's last Sync job Log and displaying to screen |
$User = Get-BTUser bob.smith@contoso.com |
Get-BTSync -User $User | Select-Object -First 1 | Get-BTLog |
To get the Discovery log for an environment use a combination of the Get-BTEnvironment and Get-BTLog cmdlets similar to the following:
# Example of getting an environment’s Discovery log |
$env = Get-BTEnvironment -Filter "TenantName -eq 'BTCloud1'" |
Get-BTLog -Identity $env |
We recommend three options for viewing retrieved Logs, displaying to the screen, displaying in a searchable grid, or exporting to a csv file.
|
To filter Logs by a particular level use the –Levels parameter for the Get-BTLog cmdlet. Possible values for the levels are Error, Warn, Info, Debug, and/or Trace.
# Example of getting a User’s Sync job Logs that are errors and displaying in a searchable grid |
Get-BTSync -User bob.smith@contoso.com | Get-BTLog -Levels Error | Out-GridView –Title ‘bob.smith@contoso.com’ |
Filter parameters can be added to the Get-BTUser cmdlet when directing its output into the Set-BTUser cmdlet for purposes of adding to a particular Wave.
# Example of using a filter for setting User Waves |
Get-BTUser –Filter "ProjectName -like 'Pilot*'" | Set-BTUser -Wave 'My New Wave' |
To export User properties and status to a file based on an assigned Wave use the Export-Csv cmdlet.
# Example of exporting Users from a given Wave to file |
Get-BTUser –Wave ‘My New Wave’ | Export-Csv –Path ‘C:\workspace\outputFile.csv’ |
The Start-BTPrepare cmdlet accepts piped input so it can be paired well with the Import-Csv cmdlet.
If you have a previously exported list of User objects as a csv file, then starting the Prepare Action against them is as simple as running the following:
# Example of importing a list of Users and starting their Prepare Action |
Import-Csv ‘C:\workspace\inputFile.csv’ | Start-BTPrepare |
If rather than User objects, you have a list of Users by attribute such as SMTP, then an approach similar to the following should accomplish your goal:
# Example of starting Prepare for an imported list of user SMTPs |
Import-Csv ‘C:\workspace\inputFileUserSMTPs.csv’ | ForEach-Object { |
$Name = $_.SMTP |
$User = get-BTUser -Identity $Name | select userid |
Start-BTPrepare -User $User |
} |
Similar to starting the Prepare Action above, the BT-StartSync and BT-StartCutover cmdlets can also handle piped input from the Import-Csv cmdlet.
# Example of importing a list of User objects and starting their Sync Action |
Import-Csv ‘C:\workspace\inputFile.csv’ | Start-BTSync |
# Example of starting Sync Action for an imported list of user SMTPs |
Import-Csv ‘C:\workspace\inputFileUserSMTPs.csv’ | ForEach-Object { |
$Name = $_.SMTP |
$User = get-BTUser -Identity $Name | select userid |
Start-BTSync -User $User |
} |
# Example of importing a list of User objects and starting their Cutover Action |
Import-Csv ‘C:\workspace\inputFile.csv’ | Start-BTCutover |
# Example of starting Cutover Action for an imported list of user SMTPs |
Import-Csv ‘C:\workspace\inputFileUserSMTPs.csv’ | ForEach-Object { |
$Name = $_.SMTP |
$User = get-BTUser -Identity $Name | select userid |
Start-BTCutover -User $User |
} |
To set a user to complete if they are in a synced status.
# Example of setting a user's migration status to Complete |
Set-BTUser -Identity bob.smith@contoso.com -MigrationState 'Complete' |
To reset the Sync Error status to be Synced after investigating and clearing any errors.
# Example of setting a user's migration status to Synced |
Set-BTUser -Identity bob.smith@contoso.com -MigrationState 'Synced' |
MailboxSize is one of the list of available -Filter parameter attributes for the Get-BTUser cmdlet. To start the Cutover Action on only Users with Mailboxes of more than a particular size the output of the Get-BTUser cmdlet with a –Filter parameter can be directed into the Start-BTCutover cmdlet using a pipe.
# Example which starts the Cutover Action for Users with Mailboxes larger than 50 GB |
Get-BTUser -Filter "MailboxSize -gt 50000000000" | Start-BTCutover |
In the gallery you may download example scripts for Power365 and Power365 Directory Sync and future products. These resources are written in PowerShell. Click the link to download the example.
This script provides a quick way to connect to your Power365 projects to run ad-hoc commands. |
This code sample can be added to any script to ask a user for their access key before running. |
This script will export the full details of every Power365 cmdlet to a text file. |
This code sample can be added to any script to verify the module is installed before running. |
This script will summarize your user’s OneDrive data to help you plan your migrations. |
This script will display the results of all user’s sync and cutover job history. |
This script will prompt for a user’s email then display and export their OneDrive Sync Log Errors. |
This script extends the existing cutover activities by managing additional user properties. |
Example scripts are shared freely without warranty or support. They are only intended to provide guidance by example to project administrators. Feel permitted to modify them to fit your needs.
New scripts and code samples are added frequently so check often to see what's new. If you have ideas for new scripts or you want to submit your own.
© ALL RIGHTS RESERVED. Feedback 이용 약관 개인정보 보호정책 Cookie Preference Center