API Tokens
What is an API Key used for?
Connecting with the BT PowerShell module requires an API key generated by an authorized client administrator in Power365.
Where do I get an API key?
Only an authorized Client Administrator can manage API keys in Power365.
How do I create a new API key?
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.
What do I do with old API keys?
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.
Additional Information
PowerShell
PowerShell
What is the PowerShell Module?
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
What is required to run the PowerShell module?
PowerShell 5.1 (recommended)
.Net 4.7.2 or above
An access token issued by an authorized client administrator
Where do I get an API key?
Only an authorized Client Administrator can manage API keys in Power365. See API Tokens for steps.
How do I install the BT PowerShell module?
Download and install the module by invoking the following from PowerShell:
Install-Module BinaryTree.Power365 -Force |
How can I verify the BT PowerShell module?
Verify the installed PowerShell module by running the following command and inspecting the output:
Get-InstalledModule -Name BinaryTree.Power365 | FL |
How can I verify that I have the latest version of the BT PowerShell module?
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 |
How do I connect to Power365?
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.
Where can I find help?
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 |
Does using the BT PowerShell API require a Power365 account?
Yes, the BT PowerShell module requires existing access to a Power365 client.
Are any additional credentials required to use the BT PowerShell API?
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.
How do I get more information about the session?
After successfully connecting to Power365 you can run the Get-BTSession cmdlet to view more information about the current session.
Can I specify particular sessions if managing multiple clients?
Yes, you can use the Set-BTProject cmdlet to manage which client session is being used in the current PowerShell context.
How do I view all of my projects?
To view a list of projects in your current session use the Get-BTProject cmdlet with no parameters.
How do I use a filter to view only some of my projects?
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*'” |
How do I create a new Migration Profile?
This operation is currently under construction and only available through the Power365 UI.
How do I assign a Migration Profile to a user?
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' |
How do I create a new Wave?
To create a new Wave run the following:
# Example of creating a new Wave |
New-BTWave -WaveName 'My Wave Name' -Project <projectID> |
How do I move a User to a different Wave?
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 |
How do I view my environments?
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'" |
How do I change my environment discovery frequency?
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 |
How do I start the discovery process for my environment?
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" |
How do I get a full list of known User properties on a source User?
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’ |
How do I get a full list of known User properties on a target User?
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’ |
How do I get a full list of known User properties by Wave?
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’ |
How do I set a Match on a User?
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 |
How do I set multiple Users’ Matches at once?
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 |
How do I start an action for a User?
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 |
How do I set migration status on a User?
This operation is under construction and currently only available in the Power365 UI.
What kinds of logs can I retrieve through the BT PowerShell module?
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).
How do I get a User’s last Sync Log?
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 |
How do I query discovery log?
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 |
What options are available for viewing the retrieved Logs?
We recommend three options for viewing retrieved Logs, displaying to the screen, displaying in a searchable grid, or exporting to a csv file.
|
There are too many Logs can I separate viewing by different levels?
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’ |
How do I use a filter to add Users to an existing Wave?
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' |
How do I export a list of User properties and status to a CSV file based on an assigned 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’ |
How do I use a script to start the Prepare Action against a list of Users?
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 |
} |
How do I use a script to start the Sync or Cutover actions against a list of Users?
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 |
} |
How do I use a script to skip the Cutover Action for a User by setting their migration status to Complete?
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' |
How do I use a script to reset the Sync Error status of a User to be Synced?
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' |
How do I start the Cutover Action on only my Users with the largest mailboxes?
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 |
Additional Information
Gallery
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.