Thursday, September 5, 2019

Teams Tenant Dial Plan Tool

I recently released a tool for configuring Direct Routing within an Office 365 tenant. Its name is the imaginative Microsoft Teams Direct Routing Tool. This tool, whilst allowing you to configure all your PSTN Gateways and Routing, did not allow you to configure the normalisation of numbers that users dial prior to being routed. This step in the process is very important because nearly all users are not going to dial phone numbers in E.164 format. As a result, prior to getting to the E.164 based routing rules we need to do some work to ensure that the numbers dialed have been converted into the right format. The number normalisation in O365 is done by the Tenant Dial Plan policies, which contain normalisation rules. The configuration of these are done using the Skype for Business Online module and bunch of pretty complicated PowerShell that really shouldn’t be inflicted on a regular human being. So to try and avoid this pain, I decided to make a sister tool to my Direct Routing Tool that will allow for simple configuration and editing of these Tenant Dial Plans. This time, in order to ensure that I came up with the most imaginative name possible for the tool, I trekked into the deepest jungles of Peru on a vision quest where after drinking several litres of Ayahuasca came up with the name “Teams Tenant Dial Plan Tool”. Enjoy…

Teams Tenant Dial Plan Tool

The Tenant Dial Plan Tool is a PowerShell based tool that allows you to configure and edit Tenant Dial Plans within Office 365 for use with Microsoft Teams Direct Routing and Calling Plans. This tool is a sister tool to my Microsoft Teams Direct Routing Tool that allows you to configure all the routing for Direct Routing within Office 365. To use the tool, simply open it with PowerShell (with the Skype for Business Online Module installed) and you will be presented with the following GUI and features:

Tool Features
  • Log into O365 using the Connect SfBO button in the top left of the tool. 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:
  • Create/Edit and Remove Tenant Dial Plan policies using the New.., Edit.. and Remove buttons.
  • Copy existing Tenant Dial Plans and all their Normalisation rules to a new Tenant Dial Plan.
  • Add/Edit Tenant Dial Plan normalisation rules. If the rule you are setting has a name that matches an existing rule, then the existing rule will be edited. If the rule’s name does not match an existing rule then it will be added as a new rule to the list.
  • Delete one or all normalisation rules from a Tenant Dial Plan policy.
  • Easily change the priority of normalisation rules with the UP and DOWN buttons.
  • Test the normalisation rules! Teams currently (at the time of writing this) doesn’t have any normalisation rule testing capabilities. So I wrote a custom testing engine into the tool providing this feature. By entering a number into the Test textbox and pressing the Test Number button, the tool will highlight all of the rules in the Dial Plan that match in blue. The rule that has the highest priority and matches the tested number will be highlighted in green. The pattern and translation of the highest priority match (the one highlighted in green) will be used to do the translation on the Test Number and the resultant translated number will be displayed in the Test Result.

  • Initial Release 1.00

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:

Download from TechNet Gallery:

Frequently Asked Questions

1. What is the deal with the OptimizeDeviceDialing setting - I can't edit it? 

In order to use the Access Prefix value that you can enter when creating a policy in the tool, a setting in the background called OptimizeDeviceDialing must also be turned on (for more details about what an Access Prefix is, refer to Ken Lasko's post about how they work in Lync). In addition to this, there is some weirdness in the PowerShell commands, which means that after you have set an Access Prefix for a policy you cannot then delete this value. You can only overwrite an existing Access Prefix with another number. When you delete the Access Prefix in the Edit dialog of the tool it will set the OptimizeDeviceDialing setting to FALSE (and leave the existing Access Prefix because it can't delete it). For example, if you already have an Access Prefix configured (as say "0") on a policy and then open the Edit dialog and remove the Access Prefix value like shown in the image below:

... then the result will show as the Access Prefix still being "0" in the main window (due to it not being able to be deleted by PowerShell) but it will update the OptimizedDeviceDialing setting to FALSE so the Access Policy is not used:

The Wrap Up

Well that was one hell of a ride. I think the Ayahuasca has nearly worn off and it's time for me to lie down. Enjoy the tool and remember, kids, don’t drink weird potions in the jungle…

Read more →

Sunday, August 18, 2019

Skype for Business 2019 Call Forward Tool

In the July 2019 update of Skype for Business Server 2019 (a release that might also be called CU1 or CU2 depending on if you include a Hotfix release that came about a month earlier) now includes some new PowerShell commands that allow you to centrally control users' call forwarding settings. This functionality used to be available via a tool called SEFAUTIL.exe in the Skype for Business resource kits in previous versions of the server releases. This is obviously great news because this is the functionality that was used all the time in practice by most organisations that I have seen.

The first question is what do we actually get with these new commands? We basically get the ability to do all the things a user can do from the Call Forward settings dialog within the Skype for Business client. This includes adding users to their Team Call Group and Delegate lists as well as setting call forward immediate, unanswered and simultaneous ring.

For more details on using the commands directly, Greig Sheridan has done a nice write up here:

Whilst it’s great to have these commands at our disposal, I still find that there is a learning curve to figuring out which settings and flags to use to achieve the call forward type that you might want in practice. So I thought it would be good to build a GUI for the PowerShell commands that looked exactly the same as the call forward settings screen from the Skype for Business client that we have all been using for many years and understand already. So that’s what I did… Introducing the Skype for Business 2019 Call Forwarding Tool:

Skype for Business 2019 Call Forwarding Tool

Tool Features:
  • No learning curve - it works the same as the call forward configuration on the Skype for Business client!
  • Get the call forwarding settings for any user on the system.
  • Edit team-call groups members.
  • Edit delegate members
  • Forward calls immediately to another number, delegates or contact.
  • Set simultaneous ring to team-call members, delegates, number or contact.
  • Control when the settings will apply ("all of the time" or "during work hours in Outlook")
  • Set the call forward settings on one or a number of users by selecting them from the user list on the right hand side of the tool.


1.00 Initial Release

Download from TechNet Gallery:


The PowerShell commands that have been supplied by Microsoft have the following limitations when compared to what can be set in the Skype for Business Client:

  • In Delegate and Team-call settings the "ring after" timer can only be set to 0, 5, 10 or 15 seconds, whereas in the Client you can set it from zero to 55 seconds (the maximum value is actually is whatever the unanswered call timer is, minus 5 seconds, which is a maximum of 55 seconds). 
  • There is no ability to select which delegates will be able to receive calls. This is represented in the client as a checkbox next to the delegate in the "Call Forwarding - Delegates" dialog. This capability is not available in the PowerShell commands at the moment.

Known Issues

Known Issue 1: Call Forward Unanswered to a Phone Number Issue

There is a bug in Skype for Business Server 2019 July 2019 update when Call Forward Immediate is disabled but Call Forward Unanswered is set to point to a number. This scenario looks like this in the Client:

From PowerShell it looks like this:

Set-CsUserCallForwardingSettings -Identity "" -DisableForwarding -UnansweredToOther "+61395554444" -UnansweredWaitTime 10

Whilst this command will be accepted by the system and look like the data has set correctly within the client the actual Call Forward will not work when you call the Client (ie. instead of the call going to the number it forwards to the user's Voicemail). This is due to a bug in the Set-CsUserCallForwardingSettings command which will hopefully be fixed in the next CU.

Known Issue 2: Call Forward Immediate to Voice Mail Issue

In Skype for Business Server 2019 July 2019 the PowerShell commands do not tell you if the user has Call Forward Immediate to Voice Mail configured. If you run the Get command it will show:

User                             :
CallForwardingEnabled            : False
ForwardDestination               :
ForwardImmediateEnabled          : False
SimultaneousRingEnabled          : False
SimultaneousRingDestination      :
ForwardToDelegates               : False
SimultaneousRingDelegates        : False
TeamRingEnabled                  : False
Team                             : {}
Delegates                        : {}
DelegateRingWaitTime             : 0
TeamDelegateRingWaitTime         : 0
SettingsActiveWorkhours          : False
UnansweredToVoicemail            : True
UnansweredCallForwardDestination :
UnansweredWaitTime               : 30

... which looks exactly the same as if there is no Call Forward set at all.

The commands also do not have a flag to allow you to set Call Forward Immediate to "Voice Mail". As a work-around for this, I have implemented the setting of Call Forward Immediate using a special SIP Address format. The SIP Address of a user's Voice Mail can be represented as their SIP Address with the following parameters after it ";opaque=app:voicemail". So, in order to forward to Voice Mail, the tool currently uses this method which the Client also respects and displays correctly as a Forward to Voice Mail. When this issue is fixed I will update the tool accordingly.

The Wrap Up

Forward away my friends! Forward away!

Read more →

Friday, February 22, 2019

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:
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:
  • 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

Download from TechNet Gallery:

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 (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 Routeto 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 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 Usageto 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 Usagethat 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 →