Microsoft Teams Direct Routing Tool

If you want to bring your own PSTN carriage via an SBC to Microsoft Teams, then you have to do quite a bit of configuration within Office 365. This configuration is done using PowerShell and can be complex to understand for someone who hasn’t worked a lot with Skype for Business Enterprise Voice deployments in the past (or even if you have!). This is especially the case if there are multiple gateways deployed around the country or world and complex failover routing is required. In order to help to make this easier, I have created a new tool that gives you a full GUI for creating, troubleshooting and testing your Direct Routing configuration.

Teams Direct Routing Overview

Microsoft has done a pretty good job of documenting the configuration of Direct Routing for people that are familiar with the concepts of Voice Routing Policies, Voice Routes, PSTN Usages, and PSTN Gateways from the days of Skype for Business Enterprise Voice. The documentation is available at Microsoft Docs here: https://docs.microsoft.com/en-us/microsoftteams/direct-routing-configure

The most helpful explanatory diagram from Microsoft’s documentation is the one below:

This diagram shows the components of Direct Routing and their relationship with each other. From a higher level it’s easiest to think of a Voice Routing Policy as being the container that has the routing elements inside of it. The Voice Routing Policy is assigned to a user and describes how calls from that user will be routed. Inside the Voice Routing Policy are PSTN Usages, which are containers that hold multiple Voice Routes. The ordering of both PSTN Usages and Voice Routes are important to the order in which calls will be sent to specific PSTN Gateways. The PSTN Gateway configuration contains all of the protocol related settings that describe information that will be sent to the physical SBCs you deploy.

The part that is most confusing about this is that Voice Routes have specific Priority settings that are assigned to them in PowerShell, which are used within a PSTN Usage to determine precedence and order of evaluation - however, this doesn’t tell the full story. The order of the PSTN Usage then functions as an overarching ordering for the Voice Routes. This relationship in diagrammatic form is relatively easy to see; however, when presented in PowerShell format it can be very difficult to understand. When designing this tool I decided to make it have the capability of helping the user easily understand the order in which routing will occur for any number dialled, by ordering everything in highest to lowest priority order.

The Microsoft Teams Direct Routing Tool

Tool Features:

• The “Connect to O365” button allows for regular and MFA based authentication with O365. Note: the Skype for Business Online PowerShell module needs to be installed on the PC that you are connecting from. You can get the module from here: https://www.microsoft.com/en-us/download/details.aspx?id=39366
• Select a User from the User drop down box to see their current Voice Policy assignment.
• Create and Remove Voice Routing Polices.
• Create, Remove, Edit and Order PSTN Usages.
• Add PSTN Usages to Voice Routing Polices.
• Create, Remove, Edit and Order Voice Routes.
• Add Voice Routes to PSTN Usages.
• Add Gateways and Regex Patterns to Voice Routes.
• Add, Remove and Edit PSTN Gateway settings.
• Enter a normalized number (ie. E164, +61400555111 style format) and click the Test Number button to see PSTN Gateways the routing order and failover choices for that specific number.
• What doesn’t it do? The tool currently doesn’t do Tenant Dial Plan configuration. This could be a future development item for a later version.

UPDATES

1.00 Initial Release

1.01 Update: 

• Added MediaRelayRoutingLocationOverride setting to PSTN Gateway Dialog

1.02 Minor Update:

• It appears that Microsoft have corrected a typo in their PowerShell module for the SipSignalingPort flag (previously had two Ls). This broke the tool's reading of the PSTN Gateway port number. Fixed in this version.

1.03 Support for Teams Module:

• Added support for Teams PowerShell Module

1.04 Full Support for Teams PowerShell Module

• The Skype for Business PowerShell module is being deprecated and the Teams Module is finally good enough to use with this tool. As a result, this tool has now been updated for use with the Teams PowerShell Module version 2.3.1 or above.

1.05 Added MFA fallback for login

• Added MFA fallback for login

1.06 Updated to support Teams Module 3.0.0

• Made changes to support changes to OnlineVoiceRoutingPolicy and TenantDialPlan formatting in Teams PowerShell Module 3.0.0.
• Teams PowerShell Module 3.0.0 is now the minimum version supported by this version.

Download from GitHub:

DOWNLOAD

Example of Tool Capabilities

As a basic example to show how the tool works, I will demonstrate making changes to the International Routing plan for Australia as created by www.ucdialplans.com (MVP Ken Lasko’s creation). The changes will be to add additional rules to allow calls to be sent via Direct Routing to On Premises PBX extensions (extension range 1000-1999). In order to do this, I will create a new Online PSTN Usage and added a Voice Route to it, then change the priority of usages and finally test that the new rule works as expected.

Step 1:  Connect to O365 and select Voice Routing Policy

After importing the basic templates in from the ucdialplans.com site (which basically involved running a PowerShell script that I’m not going to document here in detail) I then opened the Direct Routing Tool from a PowerShell window. After the GUI loaded I then clicked the “Connect to O365” button and entered my O365 administrator credentials (Note: both regular auth and MFA based auth is supported). After doing this, the tool discovered all of the existing Voice Routing Policies and displayed them in the policies drop down box:

Note: In this example I am only making changes to the International policy for brevity’s sake. 

I then selected the International policy from the Policies drop down box. The tool then loaded all of the PSTN Usages and Voice Route data associated with this Voice Routing Policy in the main window:

Step 2: Create a New PSTN Usage

I then created a new PSTN Usage that will be used to allow calls to be sent directly to an On Premises PBX that has extensions in the number range 1000-1999. To do this I clicked on the “Add Usage…” button which then displayed the Add PSTN Usage dialog. In the dialog I selected the “New” check box to indicate that I’m creating a new policy and gave it a name that aligns with the convention used for the other PSTN Usages:

After clicking OK the PSTN Usage was added to the Voice Routing Policy. However, at this point it didn’t have any Voice Route associated with it so it wasn’t capable of routing calls. You will see in the main window screenshot below that the Voice Route, Number Pattern and Gateway List columns are empty:

Step 3: Add a Voice Route to the PSTN Usage

To add the Voice Route information to the PSTN Usage I double clicked the new PSTN Usage row (this can be done by either Double Clicking on the Usage or highlight the Usage and clicking the Edit Usage button). Once this was done the Edit PSTN Usage dialog was displayed:

Step 4: Add a Voice Route

From within the Edit Usage dialog a Voice Route can be added to the usage. This can be done by either Double Clicking the PSTN Usage row or Highlighting the Usage and clicking the “Edit Voice Route” or “Add Voice Route” Buttons. When creating a new Voice Route I recommend using the Double Click or "Edit Voice Route" button because this puts you directly into the "Edit Voice Route" dialog in a single step. Once the Edit Voice Route dialog is open I assigned it a Name, Number Pattern (in this case the pattern was “^1\d{3}$” to capture the 1000-1999 extension range) and PSTN Gateway.

After filling in the dialog I clicked OK and was returned to the Edit Usage dialog where I could see that the new Voice Route info was added to the PSTN Usage:

Having completed the configuration, I clicked the OK button on the Edit Usage dialog which took me back to the main window. You will now see that the Extensions PSTN Usage has the Voice Route information in the row at the end of the Usage list:

In this case I wanted the more specific Extensions PSTN Usage to be at the top of the list because it is more specific than the other PSTN Usages. I clicked the Usage Order button to open the Usage Order dialog which allowed me to move the priority of the Extensions PSTN Usage to the top of the list and then clicked OK:

The Extensions Usage was then moved to the top of the list in the main window:

This now completed all the configuration that I needed to get calls routing to the On-Premises SBC and PBX. However, it’s important to check that the Voice Routing policy is behaving the way you want it to before moving on. In order to do this, I entered an extension number with the PBX’s extension range in the Normalized Dialled Number box and clicked the Test Number button. The results are shown below:

Second Choice:

The tool now highlights all of the PSTN Usages and Voice Routes that will get used when this number is dialled. The information in the area below the "Choice Number" drop down box shows that the first choice for route calls to this number will be the new Voice Route that I just added, which is great. However, it appears that there is a second PSTN Usage that will also be used as a second choice if the first choice is not available. In this case the second choice is matching against the “AU-SouthEast-Service” usage which was not intended as part of this configuration. This second choice route may result is calls being sent to sbc02 or even in the case of other Voice Routing Policies (that also have the “AU-SouthEast-Service” PSTN Usage) surreptitiously having the ability to dial the PBX extensions. The testing in this case has been very useful in uncovering an issue that may need to be corrected before running Direct Routing in production.

Gateway Configuration for Bonus Points: 

You may also need to create or make changes to PSTN Gateways within your O365 tenant. The good news is that the tool can also do this. Simply click on the “Gateways…” button to edit gateway settings or add and remove gateways from the tenant:

The Wrap Up

Thanks for reading the post and checking out this tool I created. You now have the power of Teams Direct Routing in your grasp: use this power wisely for good instead of evil. Best of luck with your Direct Routing configurations. Enjoy!

Read more →