Convert-RibbonSbcConfigToWord.ps1

 

Been here before? Know the deal? Jump to the revision history to see what’s in the latest update.
… or go straight to the Downloads.

The name’s a bit of a mouthful, but “Convert-RibbonSbcConfigToWord.ps1” takes the backup file from your Ribbon/Sonus SBC/UX 1000 or 2000 gateway and creates a new Word document, with all of the important(?) configuration information captured in tables.

It started life as a way to save the tedium of screen-scraping lots of fixed frames for my as-built documents, but it quickly became apparent that it would also make a useful tool for the offline review of a gateway’s config (although it ain’t no “UxBuilder”).

Convert your backups from this:

… to this:

"Before" TransformationTable-Word-v2

Features

  • Decodes gateway versions up to 9.0.1 & the SWe Lite
  • Converts and saves the config to a new Word document, and optionally makes a PDF of it too
  • Doesn’t need any Lync PowerShell modules – it’s fine on your Win 7 – Win 10 machine (which needs to have Word installed)
  • Tested on Word 2010, 2013 & 2016
  • Reasonably well debugged throughout (although time will tell of course!)
  • Use the “RedactIP” switch to strip all IP addresses from the resulting file
  • It’s easy enough to turn off an unwanted section if you’re only interested in a specific subset of the functionality, or are adapting to suit your environment
  • A “-SkipWrite” switch skips the relatively slow process of writing to Word. I added this for debugging and have left it in the released version to help anyone refining or enhancing the script
  • The script is code-signed, so no longer requires you to drop your ExecutionPolicy to “Unrestricted”. This also means you can be confident the code’s not changed since it left here
  • Uses your existing Word document template for the formatting of the table headings and table of contents – or nominate a different one from the commandline

ScriptRunning

Limitations

  • It’s not the fastest to run! Stuffing values into Word is a relatively slow process. With v2 and all options enabled allow up to 10 minutes for your average gateway. I’ve stolen Scott Hanselman’s “Progress Bars in PowerShell” to help the watched pot boil
  • Each update captures even more of the gateway’s config than before, however it still doesn’t capture EVERYTHING. There’s an enormous amount in there, and it’s growing with each release! If you find I’ve not captured a particularly valuable element of the config, feel free to revise it to suit your needs – and send me the new bits to incorporate, please. If you’re not feeling up to it, send me a sample config file and some screen-grabs of the bit you’d like to see added
  • There are MANY hash tables throughout. (This is where an integer is stored in the config file, but it’s decoded to text on-screen). I’ve put a lot of effort into capturing these, but there are going to be examples where I’ve missed one. Please send me screen-grabs and sample config files and I’ll update the script.
  • I’m largely letting Word control the width of the table columns, and you’ll find many instances where it’s done a poor job. You’ll need to edit every document the script produces to resolve this

Instructions

  1. I’ve published the script here as “Convert-RibbonSbcConfigToWord-<version>.txt” as a way of capturing the version number, but to also get around programs like Outlook that aren’t too happy being used as a delivery means for “ps1” files. So please rename it to Convert-RibbonSbcConfigToWord.ps1
  2. Backup your gateway. Export the config file. Older versions (pre 2.2.1) will save to an archive called “backup.tar.gz”, while newer versions save as “SBC_Config_<hostname>_<version>_<date>.tar”
  3. Older backups you’ll need to unzip twice to recover the “symphonyconfig.xml” document we need, whilst newer ones only need one unzip to reveal their goodness>> If you have 7-zip installed you no longer need to unzip “SBC_Config_<hostname>_<version>_<date>.tar” – just feed the .tar file as the “-inputfile”
  4. Open a PowerShell window
  5. Now feed the backup into the script! Either place the config file in the same path as the script, give the full path in the command line, or (as of v2.7) a relative path:
    PS H:\> Convert-RibbonSbcConfigToWord.ps1 -InputFile "symphonyconfig.xml" -OutputFile "CustomerSBC-config.docx"

    If you don’t specify an InputFile, the script goes looking for “symphonyconfig.xml” in its directory. If you don’t specify an OutputFile, it will re-use the name of the InputFile and save as “.docx”, overwriting any existing file of the same name in that directory. If you add the “-MakePdf” switch, it will save the same output filename as a .pdf as well

You can even batch it:

PS H:\> Get-Item "d:\path\*.tar" | foreach {.\Convert-RibbonSbcConfigToWord.ps1 -InputFile $_.Fullname -MakePdf -SkipUpdateCheck}

 

Troubleshooting

If the script won’t start, odds are you’ve run foul of a protective mechanism: the “Execution Policy”. Here’s how to Get the current value and Set it to “AllSigned”.

PS H:\> Get-ExecutionPolicy
Restricted       
PS H:\> Set-ExecutionPolicy AllSigned
Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose you to the security risks described in the about_Execution_Policies help topic at http://go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y
PS H:\>

Note that the first time you run this script you’ll have to agree to trust my code-signing cert:

PS H:\> .\Convert-RibbonSbcConfigToWord.ps1 -Inputfile symphonyconfig.xml -Verbose -MakePDF
Do you want to run software from this untrusted publisher?
File H:\\Convert-RibbonSbcConfigToWord.ps1 is published by CN=Greig Sheridan, O=Greig Sheridan, L=Petersham North, S=New South Wales, C=AU and is not trusted on your system. Only run scripts from trusted publishers.

[V] Never run  [D] Do not run  [R] Run once  [A] Always run  [?] Help (default is "D"): a

The other one you might encounter is more easily fixed. If you get this error, just do like the last line says and re-run with “.\” at the start:

Convert-RibbonSbcConfigToWord.ps1 : The term 'Convert-RibbonSbcConfigToWord.ps1' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
Suggestion [3,General]: The command Convert-RibbonSbcConfigToWord.ps1 was not found, but does exist in the current location. Windows PowerShell does not load commands from the current location by default. If you trust this command, instead type ".\Convert-RibbonSbcConfigToWord.ps1". See "get-help about_Command_Precedence" for more details.

PowerShell ISE

Some users have reported problems when running the script from a PowerShell ISE window. If that’s you, try it in a normal (but elevated) PowerShell window.
 

What’s Under the Hood

At just over almostover 5,000 more than 5,000 7,000 8,000 10,000 lines of code this script’s not compact, but structurally it is really quite simple. There are two primary components: one that reads the XML and extracts the required values; and the second is a pair of very similar functions (“WriteSection” & “WriteSectionVertically”) that creates a suitable table and dumps the values therein.

The main body of the script simply wends its way sequentially through the XML file, plucking out all of the sections of interest with essentially the same string manipulation repeating over and over again. (I had a go at it, but the unique content of each section prevented me from proceduralising this).

# ---- FXS Cards ----------
if ($NodeHardwareGroup.name -eq "FXSCards")
{
$FXSCards = $NodeHardwareGroup.GetElementsByTagName("ID")
$FXSCardColumnTitles = @("Card", "Port", "Enabled", "Port Name", "Port Alias", "Port Description", "Rx Gain", "Tx Gain", "Analog Line Profile")
if ($FXSCards.Count -ne 0)
{
ForEach ($FXSCard in $FXSCards)
{
if ($FXSCard.IE.classname -eq $null) { continue } # Empty / deleted entry
if ($FXSCard.IE.classname -eq "LINE_CARD_CONFIG_IE")
{
$FXSCardPorts = $FXSCard.GetElementsByTagName("ID")
ForEach ($FXSCardPort in $FXSCardPorts)
{
if  ($FXSCardPort.IE.classname -eq "FXS_PORT_PROFILE_CONFIG_ENTRY_IE")
{
$FXSCardObject = @($FXSCard.value, $EnabledLookup.Get_Item($FXSCardPort.IE.Enabled) <EDIT>))
$FXSCardCollection += , $FXSCardObject
}
}
}
}
$NodeHardwareData += , ("FXS Cards", $FXSCardColumnTitles, $FXSCardCollection)
}
}

… and so on.

As each section is read, the required parameters are extracted & formatted into an array. If there are multiple objects of the same type, these are also processed and an array of arrays is prepared in readiness for Word. If the section has a “Sequence” value (the ordering of entries in a Transformation Table is a prime example), this is decoded and the array entries re-ordered to represent the active sequence. Once the sequence is correct, the final array is passed to the appropriate WriteSection.

The WriteSection functions open and inspect the passed array, decoding it back into multiple constituent arrays representing column titles (“horizontal” tables only) and each table’s row. The title of the section is written to the document in the Heading1 style. If there are sub-headings (sub-tables or groups within the section), these are written as Heading2 and Heading3. We then loop through the array, writing each string therein as a new row.


 

The ENTIRE revision history is now in a separate post here.

Revision History

v11.0.0 4th February 2022

  • Added new bits in 11.0.0:
    • ‘Enforce SG Codec Priority’ in Media List
    • New section ‘Listen Port’ in SIP
    • Changed how SIP Sig Gps and SIP Recorders display ‘Listen Port’ info. (If new format is present it will be used, else legacy)
  • Added new bits in 9.0.7:
    • Added new RSA-AES-GCM cipher suites for TLS 1.2 interop
    • Added new ‘Media Codec Latch’ in SIP Sig SPs
  • Added [System.Version] declaration in Get-UpdateInfo to prevent issues where ‘9.0.4’ is apparently > ‘11.0.0’
  • Fixed bugs:
    • Routing table ‘call priority’ = ‘Emergency’ was being reported as ‘blank’ due to incorrect ID in $CRCallPriorityLookup

v9.0.7 * Not released.

  • v11 preceeded 9.0.7 due to the staggered versioning of the soft and hard platforms.

v9.0.6 * Not released.

  • No new functionality, no bugs unearthed.

v9.0.5 * Not released.

  • No new functionality, no bugs unearthed.

v9.0.4B * Not released.

  • Updated for PowerShell v7 compatibility:
    • Replaced all tests for “if -eq ”” with ‘if ([string]::IsNullOrEmpty…’
    • Added ‘[char[]]’ to multiple-value ‘.split()’ methods
    • Changed $NodeInfoArray creation from ‘.split()’ to ‘-split’ & added blank line test/continue
    • Removed reference to [Microsoft.Office.Interop.Word.WdExportCreateBookmarks] enum
  • Removed obsolete $NotificationData

v9.0.4 15th July 2021

  • Added new bit in 9.0.4:
    • Added Global Security Options / Test a Call

v9.0.3 * Not released

  • No new functionality, no bugs unearthed.

v9.0.2 28th January 2021

  • Changed Network Monitoring / Link monitors from h-table to v-table and updated to accommodate new values in 9.0.2
  • Added Protocols / IPSec / Tunnel Table
  • Changed some references to ‘<n/a>’ and ‘<Not Captured>’ to ‘<Not Available>’ to reduce ambiguity & increase consistency
  • Now stamps ‘<Not Available>’ into System / Node-Level Settings if the SweLite ID in nodeinfo.txt is blank
  • Fixed bugs:
    • Fixed bug introduced in 9.0.1 where the lower half of each SIP Server table was skipped. (Bad test of SIP Recorders)
    • Suppressed display of ‘Send STUN Packets’ in Media / Media System Configuration for the SweLite


 

Download

You’ll find a code-signed version of the script on GitHub. You’re welcome to pinch, adapt or improve upon the code with my blessing. If you encounter any problems with it please create an issue on the repo.

Help me improve the script

PLEASE let me know if you encounter any problems. All I ask is a copy of the symphonyconfig.xml file (de-identified as you wish) – or preferably a .TAR backup file – and a screen-grab from the browser to show me what it’s meant to look like on-screen.

Credits

There are many great posts out there where people have achieved awesome things with PowerShell and Word, and I’ve relied heavily on their experiences and generosity. I’ve pasted these links into the bottom of the script as well.
TOC: http://www.edrawsoft.com/automating-word-vb.php
http://carlwebster.com/documenting-a-citrix-xenapp-6-5-farm-with-microsoft-powershell-and-word-version-3/
http://stackoverflow.com/questions/14507815/powershell-word-2007-2010-2013-add-a-caption-to-table-and-move-table-3-tabs-to-r
http://mypowershell.webnode.sk/news/create-word-document-with-multiple-tables-from-powershell/
http://dilutedthoughts.com/dilutedthoughts/2012/12/19/using-powershell-to-create-a-custom-word-document
Save as PDF: http://blog.coolorange.com/2012/04/20/export-word-to-pdf-using-powershell/
Write-Progress: http://www.hanselman.com/blog/ProgressBarsInPowerShell.aspx

G.

34 Comments

  1. Hi,
    Really nice job! I just change the script a little bit because I need a different color for the first row of tables. It would have been nicer if you choose only one variable for all the first rows but it was still easy to modify.

    Here is the part I added:
    # Transformation RGB -> WdColor
    # wdColor = (red + 0x100 * green + 0x10000 * blue)
    # light orange (255,204,153)
    $MyColor = (255 + 0x100 * 204 + 0x10000 * 153)

    # Replace Colors by one common for all first rows
    $wdColorFirstRow = $MyColor

    And I replace variable after “.BackgroundPatternColor” by $wdColorFirstRow, to allow change the color in just one place.

    Many thanks for your script!!!

  2. Hi Greg
    I have used your great script several times, and the outcome is great:) But now I have an issue when I run the script from a SB2K rel. 5.0.1. It runs the script, but fails at last with this error:
    Aborted with fatal error: You cannot call a method on a null-valued expression.
    WARNING: Failed to save DOC and/or create PDF
    Have tried several times, with same result

    Do You have time to give it a shot :)

    Best regards
    David

    • Hi David,

      If you can send me the backup file I’d love to see why it’s crashing. If you’re concerned for the privacy of the data, I only need the XML, and you can obfuscate the IPs, hostnames & any other identifying details before sending it through.

  3. Hi

    Thanks for the script, however I receive the following errors when trying to run it:

    At C:\Tools\Convert-RibbonSbcConfigToWord.ps1:8 char:18
    +
    + ~
    Missing file specification after redirection operator.
    At C:\Tools\Convert-RibbonSbcConfigToWord.ps1:170 char:21
    + Sign up
    + ~
    The ampersand (&) character is not allowed. The & operator is reserved for future use; wrap an ampersand in double
    quotation marks (“&”) to pass it as part of a string.
    At C:\Tools\Convert-RibbonSbcConfigToWord.ps1:197 char:189
    + … ata-ga-click=”(Logged out) Header, go to Features”>Features <span cla …
    + ~
    The '→Mobile <span cla …
    + ~
    The '→Actions <span cla …
    + ~
    The '→Codespaces <span cla …
    + ~
    The '→</s …
    + ~
    The ampersand (&) character is not allowed. The & operator is reserved for future use; wrap an ampersand in double
    quotation marks ("&") to pass it as part of a string.
    Not all parse errors were reported. Correct the reported errors and try again.
    + CategoryInfo : ParserError: (:) [], ParseException
    + FullyQualifiedErrorId : MissingFileSpecification

  4. same issue here.

    The ampersand (&) character is not allowed. The & operator is reserved for future use; wrap an ampersand in double
    quotation marks (“&”) to pass it as part of a string.
    At C:\Users\solem\Downloads\Convert SBC to Word\Convert-RibbonSbcConfigToWord.ps1:221 char:189
    + … ata-ga-click=”(Logged out) Header, go to Features”>Features <span cla …
    + ~
    The '→Mobile <span cla …
    + ~
    The '→Actions <span cla …

    • It looks like you both have a corrupted version of the script.

      There are a couple of ways to download it cleanly:

      • Go to this link, click the Raw button (in the grey bar at the top of the code), then ^A to select all and paste the text into a file. (Back-arrow on your browser or just close the tab at this point).
      • Go to this link and download the “Source code (zip)” under “Assets” at the bottom, then unzip the script.

      Let me know if you’re still having problems with it.

  5. Hi Greig

    I’ve hit an error running the current version (which has worked before):

    fatal error @ line 1736:
    Cannot convert value “9.0.1 v260” to type “System.Int32”. Error: “Input string was not in a correct format.”

    But it only happens in PowerShell v7. So I’m OK to use the ‘usual’ version but something you might want to look at.

    Regards

    Rick

  6. Hi, Where can i get version 9.0.4. I’m tried to download new version but it’s getting error -> Item not found or file is corrupt. Every time I re-run the script it’s keep prompt me to download new version.

  7. Hi,

    i managed to download new version based on this link. https://github.com/greiginsydney/Convert-RibbonSbcConfigToWord.ps1/releases

    but i encounter this issue

    Do-Convert : Item not found or file is corrupt:
    A parameter cannot be found that matches parameter name ‘Encoding’.
    At C:xxxxxx
    + Do-Convert @Params
    + ~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Do-Convert

    • It looks like you’ve downloaded the script OK, but it looks like you’ve not told it what file you want to convert.

      If you look a little higher in that error message it should say “Cannot find path ‘C:\<path>\Convert-RibbonSbcConfigToWord.ps1\symphonyconfig.xml’ because it does not exist.

      If you just run the script on its own it assumes there’s a file called ‘symphonyconfig.xml’ and attempts to convert it into a document.

      Check out the examples by running this command:

      get-help .\Convert-RibbonSbcConfigToWord.ps1 -examples

      You can convert direct from a .TAR file if you have 7-zip installed, and if not you’ll need to manually unzip the .TAR to extract “symphonyconfig.xml”, then point the script to it (or leave it in the same folder as the script).

      Let me know if you’re still stuck.

      – G.

  8. Greg, Getting this upon execution. Using PS ver 5.117763.2268

    t C:\Sonus reports\Convert-RibbonSbcConfigToWord.ps1:278 char:19
    + Sign up
    + ~
    The ampersand (&) character is not allowed. The & operator is reserved for future use; wrap an ampersand in double
    quotation marks (“&”) to pass it as part of a string.
    At C:\Sonus reports\Convert-RibbonSbcConfigToWord.ps1:281 char:180
    + … -details-target btn-link d-lg-none mt-1 color-fg-inherit”> <svg aria …
    + ~
    The '<' operator is reserved for future use.
    At C:\Sonus reports\Convert-RibbonSbcConfigToWord.ps1:284 char:16
    +
    + ~
    The ‘ <svg aria …
    + ~
    The '<' operator is reserved for future use.
    At C:\Sonus reports\Convert-RibbonSbcConfigToWord.ps1:292 char:16
    +
    + ~
    The ‘<' operator is reserved for future use.
    At C:\Sonus reports\Convert-RibbonSbcConfigToWord.ps1:307 char:7
    +
    + ~
    The ‘<' operator is reserved for future use.
    At C:\Sonus reports\Convert-RibbonSbcConfigToWord.ps1:312 char:7
    +
    + ~
    The ‘<' operator is reserved for future use.
    At C:\Sonus reports\Convert-RibbonSbcConfigToWord.ps1:317 char:7
    +
    + ~
    The ‘<' operator is reserved for future use.
    At C:\Sonus reports\Convert-RibbonSbcConfigToWord.ps1:322 char:7

  9. Whilst I am sad to de decommissioning our SBC’s after a decade of faithful service, what a joy it was to come across this method of preserving the final config in a format that will be accessible to future staff if they need to track down what the hell an old number was doing, or why we never used extension ‘X’.

    Thanks greginsydney, you’re a legend.

Leave a Reply to Ben Eldridge Cancel reply

Your email address will not be published.

... and please just confirm for me that you're not a bot first: Time limit is exhausted. Please reload the CAPTCHA.

This site uses Akismet to reduce spam. Learn how your comment data is processed.