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.
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:
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:
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:
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!