Chat now with support
Chat with Support

Binary Tree Power365 Current - Help Center

Help Center Home Power365 Platform Tenant-to-Tenant Directory Sync Migration for Active Directory Release Notes Known Limitations Support

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?  

  1. PowerShell 5.1 (recommended)

  2. .Net 4.5.2 or above

  3. 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

 

Managing Access  

 

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.

 

Projects  

 

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*'” 

 

Profiles  

 

How do I create a new Migration Profile?  

This operation is currently under construction and only available through the Power365 UI.

Getting Started

 

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'  

 

Waves  

 

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 

 

Environments  

 

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"

 

Users  

 

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 

 

Actions  

 

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.

Getting Started

 

Logs  

 

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.

# 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
 
# Example of getting a User's first Sync job Log and displaying in searchable grid
$User = Get-BTUser bob.smith@contoso.com
Get-BTSync -User $User | Select-Object -Last 1 | Get-BTLog | Out-GridView -Title $User.UserPrincipalName
 
# Example of getting all of a User's Sync job Logs and exporting to a csv file
$User = Get-BTUser bob.smith@contoso.com
Get-BTSync -User $User | Get-BTLog | Export-Csv –Path ‘C:\workspace\logOutputFile.csv’

 

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’

 

Advanced  

 

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-BTUserFilter "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  

API Tokens

Gallery

Cmdlets

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.

 

 

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.

 

Additional Information  

PowerShell

Managing Access

Projects

Profiles

Waves

Users

Actions

Logs

Advanced

Cmdlets

Cmdlets

Note: Expand a cmdlet and use your browser's "Find on page" function to search for keywords.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Additional Information  

PowerShell

Managing Access

Projects

Profiles

Waves

Users

Actions

Logs

Advanced

Gallery

Tenant-to-Tenant

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating