Using Tags with Teams Phone Numbers to manage Phone Number assignments

I saw a post on LinkedIn the other week about a newish Teams PowerShell command to add Tags to Teams Phone Numbers.

Link here https://learn.microsoft.com/en-us/powershell/module/microsoftteams/set-csphonenumbertag?view=teams-ps to the Set command which gives a little info on how it's used.

Sounded interesting and I imagine the initial thought process is to use them to categorise your numbers based on which department or use case the number is assigned to. Makes sense and am sure a lot of people would find that useful. It got me thinking about other uses though and I wonder how this could be used to integrate into a phone number management process to automate the assignment/revocation/tombstoning/categorisation of numbers within Teams.

Most organisations will have JML processes to onboard new users, offboard leavers, tackle long term absences etc. The larger the org, the more complex this can be and having to deal with the processing of those users within Teams to assign them a number or revoke it if they've left can be resource heavy on admins if you don't have some kind of automation to deal with it.

There's also the issue of whether you might have a requirement to tombstone (don't put the number back in the 'available' pool) numbers for a set period of time before they can be reassigned to a new user/service.

Now I know there are products out there that will do this for you but obviously at a cost so I thought is there a way to do some of this natively now using PowerShell and these new cmdlets?

Setting up Tags

My first thought was setting up some standard Tags we'd apply to numbers to categorise them and show their status.

Starting simple I used this to get all my Direct Routing numbers in Teams and add two Tags to them, one to show they are used for Teams and another to say that they are "In Use".

For sake of this argument, we're assuming currently all my Direct Routing numbers are assigned to a user/thing. You could change the $Numbers variable to only select numbers where the PstnAssignmentStatus is anything other than Unassigned.

$Numbers = Get-CsPhoneNumberAssignment -NumberType DirectRouting | Select PstnAssignmentStatus, TelephoneNumber

ForEach ($Number in $Numbers) {
    Set-CsPhoneNumberTag -PhoneNumber $Number.TelephoneNumber -Tag "MS Teams"
    Set-CsPhoneNumberTag -PhoneNumber $Number.TelephoneNumber -Tag "In Use"
    Write-Output "Tags set for $($Number.TelephoneNumber)"
}

The output of this is now a list of numbers with Tags associated with my Direct Routing numbers.

Tagging a number if a user leaves

So my next thought was how we could use a Tag if a user leaves the organisation and we want to remove that number from being available to another user for a set period of time. A cool down period or tombstone process.

This might not be relevant to all organisations, you might be happy to reuse the number immediately but some organisations might want to let the number go out of use for a while before giving it to someone else.

We could create a script that runs on a set schedule to check for any users that have left the organisation and apply a Tag to the number to show it's now tombstoned for a set period of time.

##Create tombstone date 30 days from today##

$Date = (Get-Date).AddDays(30).ToString("dd-MM-yyyy")

##Set Tag to tombstoned number##

Try {
Set-CsPhoneNumberTag -PhoneNumber "+44xxxxxx" -Tag "Tombstoned until $Date"
} 

Catch {

    Write-Output "Error setting tag for +44xxxxxxx"
}

Start-Sleep -Seconds 5

Try {

Remove-CsPhoneNumberTag -PhoneNumber "+443xxxxxx" -Tag "In Use"

}

Catch {

    Write-Output "Error removing tag for +443xxxxxx"
}

We set the $Date variable to be the date we want the number to be tombstoned until, apply that as a new Tag to the number and remove the old Tag of "In Use" to show it's no longer being used.

Looking at our list of numbers now, we can see one of them now has the Tag showing it's tombstoned.

What we can do with this is now use those Tags to filter the Get-CsPhoneNumberAssignment cmdlet to show us numbers based on Tags to filter in or out numbers we want to manage.

Moving a tombstoned number back into the active pool

The final step in this example of returning that tombstoned number back into the active list of numbers is to check each day for any numbers that have a Tag with the wording "Tombstoned until xx-xx-xxxx" where the x's are the current date.

The example below adds 30 days for the sake of this example but in practice the $Date variable would just be today's date in the format we need.

##Get date we need to return numbers to pool for##

$Date = (Get-Date).AddDays(30).ToString("dd-MM-yyyy")

##Set Tag to tombstoned number##

$TombstonedNumbers = Get-CsPhoneNumberAssignment -Filter "Tags -contains ['Tombstoned until $Date']"

ForEach ($TNumber in $TombstonedNumbers) {
    Remove-CsPhoneNumberTag -PhoneNumber $TNumber.TelephoneNumber -Tag "Tombstoned until $Date"
    Set-CsPhoneNumberTag -PhoneNumber $TNumber.TelephoneNumber -Tag "Available"
    Write-Output "Tags updated for $($TNumber.TelephoneNumber)"
}

Running the above and now checking our list of numbers shows the number that was tombstoned is now showing a Tag of 'Available' and we could use our filter in Get-CsPhoneNumberAssignment to search for numbers with that Tag and we'd know they were ok to be assigned to a new user.

Thoughts

I've only spent a couple of hours looking at this so far so haven't had a chance to look at how it handles lots of Tags but the principle seems like it might work and provide a native way within Teams to handle number management and assignment without the need for 3rd party integrations.

How it works at scale across a lot of numbers would also be something you'd need to test to see if there's any impact to processing times for thousands of numbers.

The documentation on the commands isn't super detailed either yet, so I'd be interested to know if there are any other filters you can use to search Tags other than the documented "Get-CsPhoneNumberAssignment -Filter "Tags -contains ['TagName']" format.

It seems like you can only search for exact Tag matches. Trying to search by part of the name fails and using the usual * filters or changing -contains to -like produces an error.