Making sense of a TBXML
One of the things that intrigued me the most when I first started working with Lync was the Topology Builder and it’s TBXML files. Whenever I walk into a new Lync environment one of the first things I do is to open the Lync Topology Builder and pull up the existing topology to get an idea of the deployment environment, it’s configuration, and any servers present within it. I’ve always heard from the people I talked to that the TBXML files were not readable or usable without the Topology Builder because they just didn’t make sense for anyone trying to look at them.
If you open a TBXML file within a text editor you’ll notice pretty quickly that its just like most other standard XML documents, a little hard to read but it contains a great deal of information if you know what you’re looking for. This got me started on developing a way to parse this information into a usable format. I started this thinking I would be done in a couple weeks tops, and yet here I sit almost six months later hoping that whats I’m posting is ready for prime-time. Originally I wanted to be able to parse all of the topology information into a Visio Diagram, but I just couldn’t get all the information in without making it cluttered. So I chose a different route, what if I could parse the TBXML data and then output a Visio VSD for a graphical representation of the topology and then layout the rest of the information into an Excel spreadsheet that contained all the details? I started building the solution as two different scripts, but it didn’t make sense to do duplicate work so I combined them.
Enter Get-LyncTopologyInfo! Below you’ll find all the information needed to run it and a copy of the script for download.
There is one big prerequisite for building the Visio drawings, and that is the Lync Visio Stencil pack. You can download it from Microsoft’s website here. The script will look for this file to be in the “My Shapes” folder inside your documents folder (C:\Users\USERNAME\Documents\My Shapes) for you Windows 7 and Vista folks out there. Once you have that taken care of you’ll need Excel and Visio installed, I developed the script with Office 2010 but it might work with Office 2007. You’ll need to drop a copy of the TBXML into the same directory as the script and then navigate to the directory in PowerShell. Okay onto to fun part.
As you can see in the image below, the syntax for the script is .\Get-LycTopologyInfo.ps1 -vsd -xls -Source Example_Filename.TBXML
The vsd and xls flags are both optional but at least one of them must be specified, as expected the vsd flag will generate a Visio drawing and the xls flag will generate an Excel spreadsheet. The script will start importing the TBXML and parsing it for data right away and notify you what it’s doing throughout the process. Below is a screenshot of the output once completed building both the Excel spreadsheet and the Visio drawing.
When it’s finished, you should have the following two files in the directory where you ran the script. My original TBXML file was named EM.TBXML so you can see that the new file names are based upon that.
The Output – Excel
Sites and Servers Worksheet
Now let’s take a look at the Excel spreadsheet output. The first page you’ll see is the “Sites and Servers” worksheet. This list all the servers in the topology and the information about them that is stored in the TBXML file. This contains things like FQDN, Roles, Cluster Configurations, Site Information, SQL Instances, and Network Interfaces. You’ll notice it really doesn’t have IP addresses, that’s because they’re not stored in the TBXML file, only the FQDN is stored. Here are a couple of picture examples of the output based upon a couple sample topologies.
Management Info Worksheet
The second sheet is pretty simple, straight forward, and doesn’t contain a whole lot actually. It’s the “Management Info” worksheet and it contains Primary and Alternate SIP Domains, as well as any configured Dialin, Meet, and Lync Admin URLs. There not really anything else to it. Here’s a screenshot of it.
And the last of final sheet is the “Services” worksheet, this one contains the most information and not surprisingly takes the longest to build. Here you will find all of the role services for each server within the Lync Topology along with it’s UniqueID, Dependency, Port, and Interface information. These are things like Web Services, Registrar Services, File Stores, etc. The port information shows you which ports the services need along with the traffic type, owner, interface, and other details of that nature. Here’s what it looks like.
The Output – Visio
The Lync Topology Drawing
That’s it for the Excel part, now onto Visio. Anyone who has ever tried to work with Visio and Powershell scripting can probably admit it’s a frustrating experience, I know I can. Trying to come up with a way to present to data took a considerable amount of time, mostly due to the numerous trips back to the drawing board to start all over again. Now I’ll just come out with it and say that it’s not the best looking thing I’ve ever created in Visio by far, that being said it’s not the worst either. I originally wanted to created a 3D isometric drawing for the sites and servers layout, but being able to design that in Powershell so that it works with almost any number of sites and / or servers is beyond me. So I went for a simple flat site layout, and built the calculations based upon a standard 8.5″ x 11″ sheet of paper. Visio can scale it up if you need to print it larger. It’s great for just getting the information across and presenting the site/server layout, and it serves as a good starting point for building a more detailed in-depth drawing. The particular stencil it uses for a server are based upon the service roles running on that server, so it could be occasionally wrong, but I think I got them all configured right. Also you’ll notice it counts PSTN gateways as part of the server count, this was by design to provide a list of total devices in the topology. The cluster membership information presented is also presented in the left column if applicable. So without further ado, here are a couple Visio drawing examples.
Download, Notices, and Comments
And now you know what to expect when running it yourself. Below is a copy of the script, if you have any questions/comments/concerns please shoot me an email or leave a comment at the bottom of the page. Also if you run into problems or find errors when running the script let me know, as I am always trying to keep it updated.