Monday, February 3, 2020

Undocumented behaviour with dialplans on MS Teams

Who am I talking to? Eartha Kitt? Sorry, wrong number. I was trying to call my car.
I've been spending a lot of time recently messing around with MS Teams dialplans thanks to the recent release of SBC-specific translation rules. For the most part, the overall structure is the same as with Skype for Business on-prem. Some PowerShell commands are different, but most of what you already know is usable in Teams.

The biggest issue with Teams is that there hasn't been a UI for managing your Teams Enterprise Voice layout. This can be an issue if you are big into Direct Routing.  Thankfully, Microsoft recently made available what is hopefully the first round of UI enhancements to the Teams Admin Center. You can now create and manage dialplans in the UI. Microsoft has dutifully updated their documentation to help people navigate these new features.

However, there are some undocumented features that open up some interesting scenarios. Along with these are some extremely frustrating bugs that you should be aware of.

The Hidden Feature

In Skype for Business on-prem, there is a global dialplan that applies to users when there isn't an appropriate site or user-level dialplan. In the Teams documentation, the tenant Global dialplan serves a similar purpose, but there are additional features outside of what can be done on-prem. 

In Teams, Microsoft has published a series of very simple pre-defined dialplans called service country dialplans that apply to nearly every country in the world. You can see these by running Get-CsDialPlan and Get-CsVoiceNormalizationRule. They do the bare minimum, and don't do any real validation. These dialplans cannot be modified. 

The documentation goes on to say that you can define normalization rules in the tenant global dialplan or any number of tenant user dialplans. If a user tenant dialplan isn't assigned to a user, they will be assigned an effective dialplan of whatever is in the tenant global dialplan and the default service country dialplan for that user. Similarly, if a user is assigned to a tenant user dialplan, their effective dialplan will consist of the contents of the assigned tenant user dialplan along with the user's service country dialplan. The tenant dialplans have higher priority than the service country ones. 

The hidden feature is that if you have defined any normalization rules in the tenant global dialplan, those normalization rules will appear at the top of the list of any new tenant user dialplans created afterwards. This can be very useful in large organizations with many sites, but have a common set of extension dial rules. You simply have to define the rules once in the tenant global dialplan, and they will show up in every new tenant user dialplan created from that point forward. This applies to dialplans created in both PowerShell and the Teams Admin Center.

Unfortunately, there isn't a real link between the tenant global and tenant user dialplans. They are simply copies of the original. If you make a change to the tenant global dialplan, it won't be reflected in all your other dialplans. As with Skype for Business, you're still stuck with using PowerShell to manage bulk changes. Overall, it might make deploying new dialplans just a little bit simpler if you choose to take advantage of this undocumented feature.

The Bugs

Unfortunately, there are also a number of annoying bugs/oversights with the new UI. Some are cosmetic, but some will force you to re-create your dialplan if you accidentally encounter one.

Description Discrepancies

If you've used UCDialplans.com to create your dialplans, you may have noticed that I make extensive use of the Description field to let people know where the rules came along with a copyright notice. I even put in linebreaks to make it readable in the SfB Control Panel UI. These descriptions are rather lengthy and go well beyond 255 characters (sorry, not sorry).

Here are my grievances with the Description field in the MAIN dialplan UI:
  1. The Teams admin center dialplan UI doesn't respect the linebreaks and just renders a wall of text.
  2. The UI throws an error that you can only have up to 255 characters, when PowerShell allows a much higher number.
  3. The UI also throws errors about "invalid characters", such as !@#$%^*()=/\[]{}:;?<>+' Again, PowerShell has no issue with any of these characters.



What makes this even more odd, is that the UI for the individual normalization rules exhibits NONE of these issues. It renders the linebreaks properly, and doesn't complain when the description is longer than 255 characters and includes "special" characters.

The External Dialing Prefix Bug

This is a big bug, and am quite surprised it made it through QA. For a bit of background, you can configure Teams so that users can dial an external access prefix (like 9), before dialing an external number. For users coming from a legacy PBX, this is undoubtedly a boon and doesn't force them to retrain years of muscle memory. It also makes off-hook dialing more reliable. For an extended explanation of this feature, go waaay back to one of my posts from 2011 on the topic. I haven't tested it myself, but the details should still apply to Teams.

Most customers don't bother with this feature, and have been happily creating dialplans in Teams/Skype for Business Online for years via PowerShell without defining an external dialing prefix. However, if you create a new dialplan or edit an existing one in the UI, you will not be able to save your changes unless you set an external dialing prefix.

Also, this seems to have found itself into the PowerShell commands themselves, but not completely. You can create a new dialplan with New-CsTenantDialplan without an external dialing prefix, and you can make changes to an existing dialplan with Set-CsTenantDialplan, but if you try to remove an external dialing prefix via PowerShell by setting it to either $NULL or "", you will be denied.

As long as you don't set a prefix, you should be fine. Don't do what I did and set a prefix in the UI to see what happens, and expect to be able to remove it in PowerShell. This forced me to redo my entire dialplan from scratch. Thankfully, UCDialplans.com took care of that in a minute.

Spelling Mistakes

A minor quibble, but one that will force me to keep a close eye on (boo hoo me). The New/Get/Set-CsOnlinePSTNGateway command has options for setting inbound and outbound translation rules:

  • InboundPstnNumberTranslationRules
  • InboundTeamsNumberTranslationRules
  • OutboundPstnNumberTranslationRules
  • OutbundTeamsNumberTranslationRules

Do you see the problem?

Someone's spellcheck didn't work.

Conclusion


I'm trying to get this in front of the right people at Microsoft to get them to fix. Hopefully, this half of my post will have a limited shelf life. Have any of you experienced any of these issues or come across any others? Let me know in the comments.

11 comments:

  1. Dear Ken,

    Thanks a lot for sharing all this information on your blog, it is really awesome and helped me a lot already!
    I am just struggling with the external access prefix feature in a MS-Teams direct routing setup. I have configured a user specific dial plan with the external access prefix 0 and have enabled the option Optimized device dialing as well, but somehow it does not work. I always end up with the dialed number being normalized using the country specific normalization rules that come by default. Have you ever seen something similar or do you have any tip on how to make this work?

    Thanks for your help.
    Yann

    ReplyDelete
    Replies
    1. The External Access Prefix does not affect the overall normalization of the number. If you want to send a zero to your SBC, you have to do it in an outbound translation rule. For more details on how it works, look at my blog post about this from back in 2011: https://ucken.blogspot.com/2011/03/internal-extension-dialing-in-lync.html

      Delete
    2. Thanks you so much for your quick reply! I probably skipped this blog post since it was referring to MS Lync and is quite old already, but this definitely shed some light on my problem. I will give it a try and keep you posted!

      Delete
  2. Hey Ken, Can you please help me with Syntax/Examples for these trunk level translation rules mentioned below. For some reason I couldn't find any technet for the same.

    InboundPstnNumberTranslationRules
    InboundTeamsNumberTranslationRules
    OutboundPstnNumberTranslationRules
    OutbundTeamsNumberTranslationRules

    ReplyDelete
  3. Ignore my previous comment.. I got it, while playing around with Commands.

    ReplyDelete
  4. This comment has been removed by the author.

    ReplyDelete
  5. Great article. Love all your UC work.
    Is it possible the hidden feature no longer works? I created a dial plan using your UC scripts and when prompted had the Extension rules added to the global plan. Then my next dial plan I didn't add any extension rules hoping they would be copied, but they were not. Is it possible they stopped this from working?
    Any easy way to get these rules from the global into the other dial plan?
    Thanks!

    ReplyDelete
    Replies
    1. I will have to investigate this myself. I guess the thing with undocumented features is that they can go away at any time.

      Delete
    2. It is funny. I manually create a new dial plan and it copied the rules. But if I use your script from ucdialplans, it does not copy the rules it seems. Oh well, I will add them to the dial plan.

      Delete
  6. thanks but do u knwow why i am getting this error
    we cannot get the effective dial plan so the dial plan cannot be tested

    ReplyDelete
  7. Hi Mohamed, this is a very annoying issue. It's due to the account you are using not having a phone system license. Even if you are a Teams Administrator you'll need it. :)

    ReplyDelete