UcmPSTools

Installation notes

This module isnt on the PSGallery yet as I havent quite got the automation going. To use the cmdlets, download this repo and dot source Test-ImportFunctions.PS1 It will load everything into your current PS session for use!

. C:\UcMadScientist\PowerShell-Functions\Test-ImportFunctions.ps1 -Private

Build Status

Note this failure is a known issue, it's caused by cryptominers abusing Azure Pipelines. My "im not a bad repo" approval keeps popping off Azure. I've emailed the relevant team.

Tests

About UcmPSTools

UcmPSTools is a collection of PowerShell functions to ease the administration of Microsoft Teams Unified Communications features and its related services. If you're a Teams Voice engineer or are transitioning from Skype for Business to Teams, you should find alot of these functions useful.

This initially started out as a scratch pad for my commonly used UC related functions. I took it as an oppertunity to centralize alot of the code I use in my day to day work. Instead of just building things bespoke for me, I decided to clean all the functions up, heavily document them and release them on the PowerShell Gallery

Detailed posts for each function will come soon, but for now you can find inline PowerShell help and documentation to get you started.

Reporting Output

Most of the functions in this module will return a PSCustomObject indicating the success or failure of each function and some descriptive text along with it. Detailed descriptions of each functions output can be found in the comment based help in each function.

$Return.Status usually returns one of four values "OK" : The operation was sucsessful, nothing of concern "Warn" : The operation was sucsessful, but there is something you should be mindful of (We are trying to create a user that already exists, or we are running low on licences to assign). More information will be found in $Return.Message "Error" : The operation was unsucsessful, Something happend when attempting to perform the operation that we couldnt handle, check $Return.Message for more information "Unknown" : Cmdlet reached the end of the fucntion without returning anything, this shouldnt happen, if it does please log an issue on Github with your relevant log files.

$Return.Message returns descriptive text showing the connected tenant, mainly for logging, reporting or diagnosis.

If the function you are calling is working with multiple objects, then an array will be returned with multiple objects idenified by their unique attribute, such as SIP Address. (presently, no function does this, but I am planning on multiple object support for many cmdlets. See the private for more.)

Security Information

As this module frequently runs automated automations, it has been designed to hold on to creds and tokens as long as it can. As such great care should be taken to ensure that the scripts are unmodified before using them. Either download this directly from my GitHub Repo https://github.com/atreidae/ucmpstools or from the PowerShell Gallery ##todo## License

A Note on Creds.xml

The creds.xml file may be generated by any of the New-*Connection cmdlets and allows for autoreconnection should a session drop mid user migration This file is encrypted with a per user encryption key provided by Windows. These files are not portable and cannot be moved from one machine to another, or one user profile to another.

Whilst a Creds.xml is encrypted. It should be looked after like a certificate, should your user profile be compromised it is possible for someone to write a script and execute it in your profile to retrieve the stored credentials.

List of Functions (Public)

Office365 Connection Related

Functions for checking and connecting to relevant Office365 services

Note for all these functions, any of the "New-*" cmdlets will check for the Global variable $Config then look in the local folder for creds.xml before prompting the user for credentials. If the account used doesnt use MFA, then the credentials will be stored to facilitate batch operations. The specific variables used are $Global:Config.SignInAddress $Global:Config.Password $Global:Config.Override (Override URL for nonstandard usernames)

New-MSOLConnection

Clears any existing MSOL Connections and connects to MSOL, if user credentials arent presently stored in memory, the function checks for a creds.xml file in the local folder and loads it into memory. Should the Creds.xml not be found, it will prompt the user to provide credentials and write a new creds.xml in the current folder.

New-SFBOConnection

Clears any existing MSOL Connections and connects to MSOL, if user creds arent in memory, the function checks for a creds.xml file in the local folder and loads it into memory. Should the Creds.xml not be found, it will prompt the user to provide credentials and write a new creds.xml in the current folder.

New-EXHOConnection

Note: this function presently uses the old community Exchange module. I am in the process of re-writing it to support the Exchange Online 2.0 module

Grabs stored creds and creates a new Exchange Online session

This function is designed to auto reconnect to Exchange Online during batch migrations and the like. At present, it does not support modern auth. (I havent intergrated it yet)

Test-MSOLConnection

This function will test if the current PowerShell Session is connected to Office 365 Azure AD (Using Azure AD v1) and that the PSSession isnt broken If its not connected for any reason, it will return an error unless the -reconnect flag is specified, causing it to call New-MSOLConnection to attempt to reconnect instead

Test-SFBOConnection

This function will test if the current PowerShell Session is connected to Skype for Business Online via either the Skype4B module or the MicrosoftTeams module and that the PSSession isnt broken If its not connected for any reason, it will return an error unless the -reconnect flag is specified, causing it to call New-SFBOConnection to attempt to reconnect instead

Test-EXHOConnection

This function will test if the current PowerShell Session is connected to Exchange Online and that the PSSession isnt broken If its not connected for any reason, it will return an error unless the -reconnect flag is specified, causing it to call New-EXHOConnection to attempt to reconnect instead

Office365 User Management Related

Functions for creating, licencing and enabling users

Grant-UcmOffice365UserLicence

Function to check for and apply approproate licences to users Specify the UPN, Licence Code and Country Code and it will set all accordingly. It will also check for licences before applying them and return a warning when less than 5% or 5 licences are available.

PS> Grant-UcmOffice365UserLicence -upn 'button.mash@contoso.com' -LicenceType 'MCOEV' -Country 'AU'

Grants the Microsoft Phone System Licence to the user Button Mash

PS> Grant-UcmOffice365UserLicence -upn 'button.mash@contoso.com' -LicenceType 'MCOPSTNEAU2' -Country 'AU'

Grants the Telstra Calling for Office 365 Licence (Australia only)

Enable-UcmO365Service

Function for checking and enabling Office 365 Service Plans (Apps in the O365 GUI) This is great for those enviroments where the admins have turned off Skype/Teams

PS> Enable-UcmO365Service -User 'button.mash@Contoso.com' -ServiceName 'MCOSTANDARD'

Enables Skype for Business Online for the user Button Mash (Required to move the user to Teams) Users must already have the appropriate licence for the service plan to be enabled.

PS> Enable-UcmO365Service -User 'button.mash@Contoso.com' -ServiceName 'MCOPSTNEAU'

Enables the Telstra Calling for Office365 Service Plan

New-UcmOffice365User

Checks for and creates a new blank Office 365 user Handy for some situations where you need to create a user account for things that cant be sorted by a resource account.

PS> New-Office365User -UPN button.mash@contoso.com -Password "Passw0rd1!" -FirstName Caleb -LastName Sills -Country AU -DisplayName "Button Mash"

On-Prem Management related

Find-UcmSuppliedUserDetails

This function is great for converting lists of users supplied by customers into AD objects to pass to Cmdlets like Move-CsUser First it will search UserPrincipalNames that match the supplied username, if no match is found, it will then move on to checking using SamAccountName Failing that, we will prompt the user to provide an updated username, or return an error to the calling function

Import-UcmCsOnPremTools

Function to check for and import both Skype4B and AD Management tools

PS> Import-UcmCsOnPremTools

Checks for and loads the approprate modules for Skype4B and Active Directory Will throw an error and abort script if they arent found

Call Management Related

Functions related to the creation and management of Call Queues, Auto Attendants, Holidays etc.

New-UcmCsFixedNumberDiversion

Diverts a number associated with Microsoft Teams Via Microsoft Calling plans or Telstra Calling to an external PSTN number by performing the following actions

• Creates a Resource Account with named "PSTN_FWD_<inboundNumber>@domain.onmicrosoft.com" by default (Configurable using -AccountPrefix)
• Licences the account with a Virtual Phone System Licence
• Licences the account with an appropriate calling licence (Will attempt to locate a calling licence using Locate-CsCallingLicence)
• Creates an AutoAttendant with a 24 hour schedule
• Configures a forward rule in the AutoAttendant

Note: All accounts will be "Cloud