Scripting Guide

This guide explains how PowerShell scripts can be used to perform activities during mailbox migration with Mailbox Shuttle. The following topics are covered:

Adding Scripts

Scripts need to be written externally and then uploaded to Mailbox Shuttle. Scripts are uploaded by navigating to the following page in the user interface:

Configuration -> PowerShell Scripts

Each script is given a friendly name, and a description. In addition to uploading new scripts, modified scripts can be uploaded using the ‘Edit’ button, and scripts that are no longer needed can be removed using the ‘Delete’ button.

Once scripts have been added, the next step is to use them in the migration workflow.

Running Scripts

Scripts can be assigned to a default mapping for a source environment. Parameters can also be defined. This is explained below.

Assigning a Script

A script can be assigned to an environment by navigating to the Configuration -> Environments page. When an environment is selected the ‘Assign Script’ button becomes available. When adding a script the following information is required:

ItemDescription
Script NameChoose the script that you want to run from the drop down list. The script must have been previously uploaded
Execution TimeChoose when the script should run:

Before Migration: The script will run before migration starts
After Stage 1: The script will run after Stage 1 completes
After Stage 2: The script will run after Stage 2 completes
Execution TypeIndicate here from the drop down list whether the script is:

Remote Exchange: Script should run on a remote Exchange server
Locally: The script will be run by the bridgehead server
Remote: The script will be run on a remote server

Additional credentials may be required for the various execution types.

This section of the user interface allows for script parameters to be edited, or a script to be deassigned if it is no longer needed.

Adding Parameters

This section allows you to add parameters to pass to the PowerShell script. To start you need to expand the source or target environment using the small arrow next to its name. You will then see the scripts which have been assigned, and parameters can be added. There are list of parameters which Mailbox Shuttle can make available.


Parameters also can be edited, and deleted in this area.

Once a script has been assigned in this way, when migrations get to the required stage the script will be executed. The execution can be monitored in the Scripts Execution Report.

Monitoring Scripts

The progress of scripts can be monitored in the user interface by navigating to the following screen:

Managed & Operations -> Scripts Execution

General layout of scripts

In general PowerShell scripts consist of two components:
• Parameters
• Process block

See below:

param([parameter(Position=0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$UPN,
[parameter(Position=1, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][System.Management.Automation.PSCredential]$O365Credential,
[parameter(Position=2, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$SAMAccountName,
)
 
process
{
$debugpreference='continue'
# script to do things
}

Within the process block, simple try / catch statements can be used to assign licenses, set target addresses, enable archives etc.

These script examples are provided without warranty and will require modification for them to work in customer environments.

Example Scripts

These script examples are provided without warranty and will require modification for them to work in customer environments.

Update Target Address

This script which can be run after migration has finished can update the user email address to the correct one post-migration.

To use this script as part of integration with Archive Shuttle perform the following steps:

Upload it using the Configuration -> PowerShell Scripts page in the user interface, giving it a name and description.
Go to the Configuration -> Integration page and drag and drop the ‘ExecuteScript’ command into the workflow:

Click on the small ‘cog’ icon at the top left of the ExecuteScript command to configure run-parameters, and choose:

Environment: Your source environment
Execution Type: Locally
Script: The script which was just uploaded

Once it has been added the command should look like this:

Next to the cog icon are three lines, where script parameters can be specified. Click on that to configure the parameters. Ensure the screen looks like this the one below before clicking on ‘Save’.

The parameters of the script include a reference to a specific set of credentials. The name which was given to the credentials was ‘License’, it should be ensured that the credentials called ‘License’ have been added to the Credentials Editor.

Once the parameters have been saved, the command should look like this:

Save the changes to the Integration configuration, and the page should look like this:

Continue building the workflow as required for the migration, remembering to click on ‘Save’ at the end of the configuration.

Do an end-to-end test as described in the Get Migrating section of the documentation.

Here is the script for reference:

param([parameter(Position=0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$UPN,
[parameter(Position=1, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][System.Management.Automation.PSCredential]$O365Credential,
[parameter(Position=2, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$SAMAccountName
)
process
{
$debugpreference='continue'
try
{
Import-Module ActiveDirectory
 
Set-ADUSer $SAMAccountName -Replace @{targetAddress="SMTP:$SAMAccountName@Domain.onmicrosoft.com"} -EA Stop
 
Write-Debug "$UPN - Successfully Set Target Address For Mail User $UPN"
}
catch
{
# if it is not possible to change the target address, script ends
Write-Error "$UPN - Failed to set target SMTP Address $UPN. Error $($Error[0])"
}
 
}

Setting License Options

Whilst there is a workflow step that can be used to assign a license, it is also possible and sometimes desirable to use PowerShell. It is necessary to put in the name of the license to assign, and also the region / usage location.

The script is as follows:

param([parameter(Position=0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$UPN,
[parameter(Position=1, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][System.Management.Automation.PSCredential]$O365Credential,
[parameter(Position=2, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$SAMAccountName
)
process
{
$debugpreference='continue'
try
{
Import-Module MSOnline
 
Connect-MsolService -credential $O365Credential
 
Set-MsolUser -UserPrincipalName $UPN -UsageLocation US
 
Set-MsolUserLicense -UserPrincipalName $UPN -AddLicenses <Domain:SKUID> -EA Stop
 
Write-Debug "$UPN - Successfully Set License for user $UPN"
 
Get-PSSession | Remove-PSSession
 
}
catch
{
# if it fails then attempts to add license with license options
Write-Warning "$UPN - Could not add license. User may already have a license assigned. Error $($Error[0])"
 
}
}

Enable Litigation Hold

This script can be used to place a mailbox on litigation hold:

param([parameter(Position=0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$UPN,
[parameter(Position=1, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][System.Management.Automation.PSCredential]$O365Credential,
[parameter(Position=2, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$SAMAccountName
)
process
{
 
try
{
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $O365Credential -Authentication Basic -AllowRedirection
Import-PSSession $Session -CommandName Set-Mailbox,Add-MailboxPermission
 
set-mailbox $UPN -LitigationHoldEnabled $true -LitigationHoldDuration $LitHoldDuration
 
Write-debug "$UPN - Successfully Set Litigation Hold for $UPN for $LitHoldDurtation days"
 
Remove-PSSession $Session
}
catch
{
# if it fails then attempts to add license with license options
 
Write-Error "$UPN - Could not set litigation hold for account $UPN for $LitHoldDuration days . Error $($Error[0])"
}
 
}

Enable Remote Archive

If needed an on-premise mailbox can have a remote Office 365 archive added to it. The script to do that is as follows:

param([parameter(Position=0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$UPN,
[parameter(Position=1, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][System.Management.Automation.PSCredential]$O365Credential,
[parameter(Position=2, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, mandatory=$true)][string]$SAMAccountName
)
process
{
Try
{
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -connectionURI https://server.domain.com/PowerShell -Authentication basic -Credential $LocalCred -EA Stop
 
Import-PSSession $Session -CommandName Enable-RemoteMailbox -AllowClobber -EA Stop
 
Enable-RemoteMailbox $UPN -Archive -EA Stop
 
Write-Debug “Successfully enabled remote archive for $UPN”
 
Get-PSSession | Remove-PSSession
}
Catch
{
Write-Debug "Could Not Create remote archive. Error - $($Error[0])"
}
}
Print Friendly, PDF & Email
Updated on December 10, 2018

Was this article helpful?

Related Articles