The Unified Messaging Troubleshooting Tool is a diagnostics cmdlet which every administrator should run whenever someone desperately (or not) comes to them and says "Help! My voicemail isn't working!". The tool executes a set of tests and outputs the possible root causes for any detected issues and the possible solution for those. Simple, fast and efficient, just the kind of tool you need in your daily IT adventures.

Since we released the tool a while back, I've been receiving requests to post about it here on EHLO. As more and more organizations are starting to move away from the typical enterprise deployment model to a completely online world in Office 365, I thought this would be the right time to attend such requests.

So, have you been using the tool? If not, here's something to get you started!

Configuring the Windows PowerShell default execution policy on Windows 7

If you are running the tool in Windows 7, by default it won't be given permission to execute Powershell scripts. This is due to the default execution policy granted by Windows PowerShell which is set to Restricted, so the moment you double click on the shortcut for the tool on your desktop, you get a nasty error message:

Microsoft.Exchange.UM.TroubleshootingTool.ps1 cannot be loaded because the execution of scripts is disabled on this system. Please see "get-help about signing" for more details.

To bypass this, execute the following steps on your box:

  1. Start a new Powershell window as Administrator(run as Administrator)
  2. Run the following command: Set-ExecutionPolicy RemoteSigned

This will grant Windows Powershell permissions to execute all scripts and configuration files, as long as they're signed by a trusted publisher. Because the troubleshooting tool is a signed Powershell script, it'll be granted the permissions to execute.

Running the tool

You are now ready to run the tool. Double click on the UM Troubleshooting tool shortcut on your desktop and type Test-ExchangeUmCallFlow

PS C:\>Test-ExchangeUMCallFlow
Cmdlet Test-ExchangeUMCallFlow at command pipeline position 1
Supply values for the following parameters:
Mode:

The troubleshooting tool supports two operating modes:

  • Gateway: Emulates a call, as if it was coming from a SIP Gateway.
  • SIPClient: Emulates a call, as if it was coming from a Lync server.

Say you're running the tool to verify Bob's TelEx extension (x12345). When prompted about the execution mode, you should go ahead and confidently type Gateway.

PS C:\>Test-ExchangeUMCallFlow
Cmdlet Test-ExchangeUMCallFlow at command pipeline position 1
Supply values for the following parameters:
Mode: Gateway
NextHop:

The troubleshooting tool will now prompt you for the NextHop. This should be the IP address or FQDN that the tool must connect to. Your NextHop will vary, depending on whether you're running the tool to verify the UM configuration of a mailbox in Office365 or a mailbox hosted in your on-premises Exchange organization.

If you're verifying a mailbox hosted in the cloud, you should enter the FQDN of the SBC device, which will in turn forward the call to one of our UM servers.

If you're running the tool against an on-premises mailbox, you should enter the FQDN of your Unified Messaging server.

PS C:\>Test-ExchangeUMCallFlow
Cmdlet Test-ExchangeUMCallFlow at command pipeline position 1
Supply values for the following parameters:
Mode: Gateway
NextHop: Umserver.constoso.com
Diversion:

The last information required is the diversion header to be used. It can be as simple as just the extension number to be verified, or a (somewhat) complex History-Info header, as those might also be used by SIP devices interested in preserving the information on how a call originated.

Here's an example of a very complex History-Info in case you'd like to try it out:

History-Info:<sip:12345@contoso.com;user=phone?Reason=SIP%3Because%3D487%3Btext%3DTimeout>;index=1,<sip:7890@contoso.com;user=phone?Reason=SIP&m#62;;index=1.1

So go ahead and enter the last parameter required:

PS C:\>Test-ExchangeUMCallFlow
Cmdlet Test-ExchangeUMCallFlow at command pipeline position 1
Supply values for the following parameters:
Mode: Gateway
NextHop: Umserver.constoso.com
Diversion: 12345

That's it! The tool will then execute a set of tests and output any issues detected.

PS C:\>Test-ExchangeUMCallFlow
Cmdlet Test-ExchangeUMCallFlow at command pipeline position 1
Supply values for the following parameters:
Mode: Gateway
NextHop: Umserver.constoso.com
Diversion: 12345
 
The diagnostic test identified a problem.
 

Task : Resolving "UmServer.contoso.com" to an IP address
Status : Failed
Reason : It is not possible to resolve "UmServer.constoso.com" from this machine. Details: No such host is known
Solution : Confirm that the server name "UmServer.contoso.com" is correct and that it can be accessed from this computer.
 
 
Traces for this diagnostic test can be found at 'C:\Users\Administrator\AppData\Roaming\Microsoft Exchange 2010 UM Troubleshooting Tool'.

By the way, did you notice the last lines outputted by the tool? Here is what is says:

Traces for this diagnostic test can be found at 'C:\Users\Administrator\AppData\Roaming\Microsoft Exchange 2010 UM Troubleshooting Tool'

In addition to the information returned by the tool, a set of very, very important traces are automatically generated by the tool:

  • UMTool_Collaboration: RTC stack traces
  • UMTool_DiagnosticLog: Lists the tests executed by the tool and their results
  • UMTool_S4: S4 stack traces
  • UMTool_SIPMessageLogs: The full SIP traces for the test call executed

The UM team would love to hear stories where the Unified Messaging Troubleshooting tool saved your day! We'd love as well to hear any other asks you might have. Let us know by posting your comments on this blog.

Bernardo Sana