Using UcmPsTools in your Automation

UcmPsTools is a robust set of Cmdlets that allow for many management tasks in both the migration of users from Skype for Business to Teams and for the day-to-day management of Voice features in Teams.

Preparing to use UcmPsTools in your environment

Whilst each of UcmPsTools Cmdlets is designed to be helpful when run by itself, they are most potent when used together as part of your own automation or as tools to speed up the development of your own scripts for working with Teams.

Installation

Getting UcmPsTools into your environment is simple. Head over to Quickstart for many options on getting UcmPsTools up and running.

Next, it's as simple as declaring a few variables and saving some credentials (optional) and your good to go.

Logging variable

The first one is for logging, as almost every function in UcmPsTools uses the Write-UcmLog Cmdlet. This function will put logs into the working folder unless the variable is specified.

Credentials

As this module frequently runs automated actions, it needs to be connected to the relevant Office 365 services to function.

You can connect to these services yourself before calling any UcmPsTools cmdlets and UcmPsTools will function normally. However, should the connection break, mid-batch, the cmdlets will detect this and exit.

Or, you can allow UcmPsTools to manage these connections for you, using the Connect-Ucm* Cmdlets allows for UcmPsTools to store connection details and automatically attempt to reconnect using stored credentials or tokens.

See Connections and Modules on how to use these cmdlets, and Security in UcmPsTools for information on how these details are encrypted, stored and used.

Presently, UcmPsTools supports Plain and OAuth Authentication. Accounts with MFA will require human intervention. I plan on adding Token based authentication soon

Compatibility with automation platforms

UcmPsTools is currently tested against Windows PowerShell on Windows 11, Windows Server 2019 and Pwsh 7 on Ubuntu. However, I cannot vouch for all its dependencies, such as the Teams PowerShell Module or the MSOL PowerShell Module.

I test in the PowerShell ISE, Windows Terminal and VsCode. Still, everything in UcmPsTools has been designed so that results are returned as objects on the pipeline and avoiding using things like Write-Host so you can easily capture output for assessment by your automation tools, See Reporting and Logging for more information.

Example Script using UcmPsTools

Here's a modified version of one of the scripts I use in production to prepare Teams Users before moving Skype4B users to the cloud.

Script Objective

In the example below, I use UcmPsTools to;

• Set the location of UcmPsTools Logfiles

• Create a report object

• Check we are connected to MSOL

• List every user in the report

• Check each user's licences and assign them if required

• Check each user's service plans and assign them if required

• Add items to the user report from above

These aren't the only things you can do. I also have scripts that move users, assign them policies and create large batches of number diversions. All using UcmPsTools at their core and I make all of this freely available to you, to use in whatever way you need within the constraints of the MIT licence

Example Code

This code isn't directly executable. I've removed large chunks of syntax to make it easier to understand how UcmPsTools works and reduce clutter rather than being a perfect "HowTo."

#Migrate-SkypeUsersToTeamsPrep

##Set variables

$Folder = "C:\UcMadScientist\" #Folder containing migration batches?
$File = "C:\UcMadScientist\UserMigration.csv" #File we are working with?

##log file location (Used by UcmPsTools Cmdlets!)
$LogFileLocation =  $PSCommandPath -replace '.ps1','.log' #Where do we store the log files? (In the same folder by default)

##import files
cd $Folder
$users = Import-CSV $File -ErrorAction Stop 

## Use UcmPsTools to start a report for our actions
  Initialize-UcmReport -Title "Step 1" -Subtitle "Licence and Service Plan Validation/Assignment"

## Use UcmPsTools to check we are connected to MSOL and reconnect if possible. If not, throw an error
  $return = (Test-UcmMSOLConnection -reconnect)
  if ($return.status -eq "Error")
  {
  ## Use UcmPsTools to write an entry to our logfile and display a message on screen that we arent connected with a log level of Warning
   Write-UcmLog -message "We arent connected to MSOL Service. Please run Connect-MsolService and try again" -Severity 3
   Return
  }

  #Process Each User
Foreach ($username in $users) 
  { 
  
    ## Use UcmPsTools to write an entry to our logfile and display a message on screen with a log level of INFO
    Write-UcmLog -message "Processing User $Username" -Severity 2
  
    ## Use UcmPsTools to add a new user to the report.
    New-UCMReportItem -LineTitle "Username" -LineMessage "$username"

    ## Use UcmPsTools to check the user for Licences, and add them if required

        #Use UcmPsTools to check/add Enterprise Voice (MCOEV) Licence to the user
        $step = (Grant-UcmOffice365UserLicence -upn $user.upn -LicenceType 'MCOEV' -Country 'AU')

        #Use UcmPsTools to store the results of the above check against the user in the report
        New-UcmReportStep -Stepname "EV Licence" -StepResult "$($Step.status) $($step.message)" 

        #Use UcmPsTools to check/add Telstra Calling (MCOPSTNEAU2) Licence to the user
        $step = (Grant-UcmOffice365UserLicence -upn $user.upn -LicenceType 'MCOPSTNEAU2' -Country 'AU')

        #Use UcmPsTools to store the results of the above check against the user in the report
        New-UcmReportStep -Stepname "TCO Licence" -StepResult "$($Step.status) $($step.message)"
    
  
    ## Use UcmPsTools to check the users Service Plans and enable them if required

        #Use UcmPsTools to check the Teams Service Plan
        $step = (Enable-UcmO365Service -upn $user.upn -ServiceName TEAMS1)
        #Use UcmPsTools to store the results of the above check against the user in the report
        New-UcmReportStep -Stepname "Teams Service Plan" -StepResult "$($Step.status) $($step.message)"

        #Use UcmPsTools to check the Skype for Business Online Service Plan (Required to Migrate User from OnPrem to Online
        $step = (Enable-UcmO365Service -upn $user.upn -ServiceName MCOSTANDARD)
        #Use UcmPsTools to store the results of the above check against the user in the report
        New-UcmReportStep -Stepname "SFBO Service Plan" -StepResult "$($Step.status) $($step.message)"

        #Use UcmPsTools to check the Telstra Calling Service Plan
        $step = (Enable-UcmO365Service -upn $user.upn -ServiceName MCOPSTNEAU)
        #Use UcmPsTools to store the results of the above check against the user in the report
        New-UcmReportStep -Stepname "TCO Service Plan" -StepResult "$($Step.status) $($step.message)"
        
  } #Repeat for the next user

#All users are complete. Tell UcmPsTools to close the report.
Complete-UcmReport

#Export the report as a HTML file and a CSV to the current folder
Export-UcmHTMLReport | out-null
Export-UcmCSVReport | out-null

Script Output

Once the script completes, I'll get a log file that looks like this (generated by UcmPsTools)

And a HTML file like this

and finally, a CSV file, like this