PowerShell

What is the Binary Tree PowerShell Module?

The Binary Tree 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 Binary Tree 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 Binary Tree 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 ‘How do I get a new API key?’ below 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.

 

How do I get 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:

  1. Log in to Power365.
  2. Select API Tokens from the Manage section of the top left menu.
  3. Click New to create a new key.
  4. Follow the prompts.
  5. Give the key a Name.
  6. Select a Role (Read, Write).
  7. Select an Expiration date.
  8. 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.

(click to view larger)

 

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.

  1. Log in to Power365.
  2. Select API Tokens from the Manage section of the top left menu.
  3. To Delete a key click on the DELETE action on that key’s row in the API Keys table. When prompted, confirm the deletion.
  4. 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.

 

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

 

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, or Cutover 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, and Get-BTCutover 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

 

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