Paul's UC and Dev/Ops Blog

Document Your ThinkTel DIDs

Paul Vaillant — Fri, 05 Jun 2015 00:00:00 UTC

Documentation is important. It’s key to being able to work together in teams and not have to rely on information based informally from person to person. I’ve talked before about how to document your PowerShell scripts but did you know you can also label each DID on your ThinkTel SIP trunk? This lets you record who or what the DID is for and can be very useful since it is shown in CDR reports, letting you know who originated or received individual calls. This can also be a big step towards not needing to document your phone number assignments in a separate Excel spreadsheet.

While the script below is specifically for Microsoft Lync or Skype for Business, it could easily be adapted for any system where the information on the allocated DID and the assigned user was available using PowerShell. This could be a backend database, a directory of some kind or web service API.

Get uControl Labels

Using previously shown PowerShell (see Keeping Lync Unassigned Numbers Updated), we start by downloading all the DIDs and their labels from uControl.


$sipTrunkDidsUrl = "https://api.thinktel.ca/REST.svc/SipTrunks/{0}/Dids?PageFrom=0&PageSize=100000" -f $SipPilotNumber
$didsList = Invoke-RestMethod -URI $sipTrunkDidsUrl -Credential $Credential -Method GET -ContentType "text/xml"
if(-not $didsList -or -not $didsList.ArrayOfTerseNumber) {
  Write-Error "Failed to load or parse DIDs on SIP Pilot $SipPilotNumber"
  exit
}

$existingLabels = @{}
$didsList.ArrayOfTerseNumber.TerseNumber | foreach {
  $existingLabels.Add($_.Number, $_.Label)
}

One note, and you’ll see this below too, I’m using Invoke-RestMethod here so this will need to be run on a machine with PowerShell 3.0+ since that’s when this cmdlet was introduced. This was released with Windows 2012 R1 so hopefully you have at least that. If you did have Windows 2008 R2 for some reason, my sympathies, but you could use System.Net.WebClient instead. If anyone has this situation, and is interested in a version of this script for PowerShell 2.0, let me know.

Get Labels From Skype for Business

Next step, again using previously shown PowerShell (see Managing Your Lync Phone Numbers), we get a list of all numbers assigned and a label to represent to what they are assigned to.


$currentLabels = @()
function AddCurrentLabel($telUri, $label) {
  if($telUri -notmatch '^tel:+1') {
    Write-Warning "Skipping $telUri ($label) because it doesn't start with tel:+1"
  } elseif($telUri -match ';ext=') {
    Write-Warning "Skipping $telUri ($label) because it contains an extension"
  } else {
    # $telUri will start with tel:+1 so let's skip that
    $number = $telUri.Substring(6)
    $currentLabels.Add($number, $label)
  }
}
Get-CsUser -Filter {LineURI -ne $Null} | foreach {
  AddCurrentLabel($_.LineURI, "User " + $_.SipAddress)
}
Get-CsUser -Filter {PrivateLine -ne $Null} | foreach {
  AddCurrentLabel($_.PrivateLine, "User " + $_.SipAddress + " (private line)")
}
Get-CsAnalogDevice -Filter {LineURI -ne $Null} | foreach {
  AddCurrentLabel($_.LineURI, "Analog Device " + $_.DisplayName)
}
Get-CsCommonAreaPhone -Filter {LineURI -ne $Null} | foreach {
  AddCurrentLabel($_.LineURI, "Common Area Phone " + $_.DisplayName)
}
Get-CsRgsWorkflow | ?{ $_.LineURI } | foreach {
  AddCurrentLabel($_.LineURI, "RGS Workflow " + $_.PrimaryAddress)
}
Get-CsDialInConferencingAccessNumber -Filter {LineURI -ne $Null} | foreach {
  AddCurrentLabel($_.LineURI, "Dial In Conf Number " + $_.DisplayName)
}
Get-CsExUmContact -Filter {LineURI -ne $Null} | foreach {
  AddCurrentLabel($_.LineURI, "ExUmContact " + $_.DisplayName)
}
Get-CsTrustedApplicationEndpoint -Filter {LineURI -ne $Null} | foreach {
  AddCurrentLabel($_.LineUri, "Trusted App Endpoint " + $_.SipAddress)
}
Get-CsMeetingRoom -Filter {LineURI -ne $Null} | foreach {
  AddCurrentLabel($_.LineURI, "Meeting Room " + $_.SipAddress)
}

For users, the choice of label is obvious (name and SIP address), and for other objects there is generally a description or display name available. In a worse case scenario, I find it sufficient to just note the kind of usage.

Find Updates

Then we compare the two hashes: * We check for any labels that are only in the current set; those are ones that don’t exist on the SIP trunk since at worse an empty label would be returned for each DID, * We check for any labels that are only in the existing set; those are old ones that don’t exist in Skype for Business, * We check all the labels in both to see if they match, other wise we update it


$newLabels = @{}
foreach($num in $currentLabels.Keys) {
  if($existingLabels.ContainsKey($num)) {
    # this is a valid number on the trunk
    if($currentLabels[$num] -ne $existingLabels[$num]) {
      # the label needs to be updated
      $newLabels.Add($num, $currentLabels[$num])
    }
  } else {
    # this is not a number on the trunk
    Write-Warning "Skipping $num since it isn't on the trunk"
  }
}

PUT data back to uControl

Last, but not least, we then send this data back to uControl.


foreach($num in $newLabels.Keys) {
  $label = $newLabels[$num]
  Write-Verbose "Updating $num ($label)"

  # we actually need to start by getting the current number information
  # this ensures we don't clear out an existing number translation
  $sipTrunkDidUrl = "https://api.thinktel.ca/REST.svc/SipTrunks/{0}/Dids/{1}" -f $SipPilotNumber,$num
  $d = Invoke-RestMethod -URI $sipTrunkDidUrl -Credential $Credential -Method GET -ContentType "application/json"
  if(-not $d -or $d.Number -ne $num) {
    Write-Error "Failed to load information for DID $num"
    continue
  }

  # update the DID label
  $d.Label = $label

  # now POST this back to $sipTrunkDidUrl
  if($PSCmdlet.ShouldProcess($num,"Update DID label")) {
    Invoke-RestMethod -URI $sipTrunkDidUrl -Credential $Credential -Method "POST" -ContentType "application/json" -Body $d
  }
}

You might wonder why I’m downloading each DID instead of just building it the response in memory. The initial GET query we did for all the DIDs doesn’t have all the information for the DID. So features like number translation would be over-written if we didn’t include it in the PUT body. You can see the difference since the initial GET query doesn’t return an ArrayOfDid, instead it’s an ArrayOfTerseNumber, with TerseNumber only having Number and Label instead of all the DID information.

Note too the $PSCmdlet.ShouldProcess used above. That, plus [CmdletBinding(SupportShouldProcess=$true)] above param() is what makes -WhatIf work so that you can see what changes would be made before actually committing to making the changes.

And that’s all there is to it. Now, if you set this up as a scheduled task, your current number assignments will be reflected automatically into the uControl web portal.

Download the Script

Update-ThinkTelDidLabels.ps1

Create a PDF from Images with PowerShell

Paul Vaillant — Thu, 28 May 2015 00:00:00 UTC

I don’t know how your organization is but my experience is that all organizations have processes and invariably one, or more, of those processes can be byzantine. I experienced this first hand recently when I was asked to provide PDF versions of expense receipts.

My Workflow

So what I’ve been doing is taking a picture of receipts using my Windows Phone, which is set to upload a copy of my pictures to my OneDrive and then I was sending those pictures in. This was very easy and very convenient for me since I travel with my phone. I didn’t need to wait to get back into the office and I didn’t need yet another device in my bag or need to stop and setup something connected to my laptop. How to provide PDFs without completely doing away with my convinience?

NOTE: for my purposes these are receipts, but the same could apply for anything that you’re taking a picture of but want to convert into Word or PDF format, possibly with additional content.

Word.Application

This is the Apollo 13 moment where they put one of everything that they have in the capsule on the table in front of the engineers and ask them to come up with a way to put a square filter in a round hole.

I have Office, and Word can insert images into a document and save it as a PDF, so now I just have to automate the process.

So first thing is that I want some flexibility in how I call this, specifically so I can use ls and where to select the files I want, so I need to be able to accept images from the pipeline. Sometimes I also want to create a single document instead of more than one, and sometimes I want to remove the images once they have been converted, so I have a parameters for those options.


[CmdletBinding()]
param(
	[Parameter(ValueFromPipeline=$true)][string[]]$Images,
	[Parameter()][string]$CombinedFilename
)

Next I do the initial setup of creating a new instance of Word. I also setup some variables for use in the combined file case.


BEGIN {
	$word = New-Object -ComObject Word.Application

	$doc = $null
	$first = $true
	if($CombinedFilename) {
		Write-Verbose "Creating combined document"
		$doc = $word.Documents.Add()
	}
}

Creating Documents and Saving Them

Now we need to actually create the documents. For each images, we create a new document as needed, use AddPicture to add it to the current document and either save/close the document (if they are separate documents) or insert a new page for combined documents.


PROCESS {
	foreach($img in $Images) {
		if(!$doc) {
			$doc = $word.Documents.Add()
		}

		#6 is [Microsoft.Office.Interop.Word.wdunits]::wdstory
		$word.Selection.EndKey(6) | Out-Null
		$word.Selection.InlineShapes.AddPicture($img) | Out-Null
		if($CombinedFilename) {
			if($first) {
				$first = $false
			} else {
				$word.Selection.InsertNewPage()
			}
		}

		if(!$CombinedFilename) {
			$pdf = $img.Substring(0, $img.LastIndexOf('.')) + ".pdf"
			#17 is [microsoft.office.interop.word.WdSaveFormat]::wdFormatPDF
			$doc.SaveAs([ref]$pdf, [ref]17)
			#0 is [microsoft.office.interop.word.wdsaveoptions]::wdDoNotSaveChanges
			$doc.Close([ref]0)
			$doc = $null
		}
	}
}

One thing to note; I’m using the numeric value for WdSaveFormat and WdSaveOptions for testability. Specifically, I want to be able to test my scripts without having Word installed or the COM interop classes loaded.

Wrapping It Up

With all the hard work done, now it’s just about saving the combined file, if that’s what we’re creating, and quitting Word.


END {
	if($CombinedFilename) {
		$doc.SaveAs([ref]$CombinedFilename, [ref]17)
		#0 is [microsoft.office.interop.word.wdsaveoptions]::wdDoNotSaveChanges
		$doc.Close([ref]0)
	}

	#0 is [microsoft.office.interop.word.wdsaveoptions]::wdDoNotSaveChanges
	$word.Quit([ref]0)
	$word = $null
}

Let’s Not Forget Testing

I’ve talked about testing before so let’s not forget this important part. The testing in this case is a little different than the last time. This time we need to create Mocks. No problem, Pester supports mocking.

The first step is to setup functions to mimic the Word APIs we’re going to call. One stub function for each thing we’re going to test happened.


function QuitWord { param($opts) }
function AddDocument { }
function AddPicture { param($path) }
function InsertNewPage { }
function SaveDocument { param($path, $opts) }
function CloseDocument { param($opts) }

Next is some helper functions to make the mock statements cleaner. Note that some of the Word methods use reference parameters so in PowerShell we use [ref] but that results in a PSReference type object. Pester would have a hard time matching those with the ParameterFilter so before the call to the stub function, I unwrap the value from the PSReference object.


function NewDocument {
  $doc = New-Object psobject
  $doc | Add-Member -MemberType ScriptMethod -Name "SaveAs" -Value {
    param([ref]$path,[ref]$opts)
    SaveDocument $path.Value $opts.Value
  }
  $doc | Add-Member -MemberType ScriptMethod -Name "Close" -Value {
    param([ref]$opts)
    CloseDocument $opts.Value
  }
  return $doc
}

function NewWordApp {
  $docs = New-Object psobject
  $docs | Add-Member -MemberType ScriptMethod -Name "Add" -Value { AddDocument }

  $shapes = new-object psobject
  $shapes | Add-Member -MemberType ScriptMethod -Name "AddPicture" -Value {
    param($path)
    AddPicture $path
  }

  $sel = New-Object psobject @{InlineShapes = $shapes}
  $sel | Add-Member -MemberType ScriptMethod -Name "EndKey" -Value {
    param($opts)
    # ... no-op
  }
  $sel | Add-Member -MemberType ScriptMethod -Name "InsertNewPage" -Value {
    InsertNewPage
  }

  $word = New-Object psobject @{Visible = $false; Documents = $docs; Selection = $sel}
  $word | Add-Member -MemberType ScriptMethod -Name "Quit" -Value {
    param([ref]$opts)
    QuitWord $opts.Value
  }

  return $word
}

Finally the actual tests. You can see one mock statement for each of our stub functions.


Describe "Convert-JpgToPdf.ps1" {
  Mock New-Object { NewWordApp } -Verifiable -ParameterFilter { $ComObject -eq 'Word.Application' }

  Mock QuitWord { param($opts) }
  Mock AddDocument { NewDocument }
  Mock AddPicture { param($path) }
  Mock InsertNewPage { }
  Mock SaveDocument { param($path, $opts) }
  Mock CloseDocument { param($opts) }

  Context "Images on the command line as separate documents" {
    $images = @("fake-image1.jpg", "fake-image2.jpg")
    & $cmd -Images $images

    It "creates a word instance" {
      Assert-VerifiableMocks
    }

    It "creates 2 documents each with 1 image" {
      Assert-MockCalled AddDocument -Exactly -Times 2
      foreach($img in $images) {
        Assert-MockCalled AddPicture -ParameterFilter { $path -eq $img }
      }
      Assert-MockCalled InsertNewPage -Exactly -Times 0
      Assert-MockCalled SaveDocument -Exactly -Times 2
      foreach($img in $images) {
        $pdf = $img -replace '\.jpg$','.pdf'
        Assert-MockCalled SaveDocument -ParameterFilter { $path -eq $pdf -and $opts -eq 17 }
      }
      Assert-MockCalled CloseDocument -Exactly -Times 2 -ParameterFilter { $opts -eq 0 }
    }

    It "closes word nicely" {
      Assert-MockCalled QuitWord -Exactly -Times 1 -ParameterFilter { $opts -eq 0 }
    }
  }
}

There’s also a context for images on the command line as a combined document and the same (separate and combined document) contexts for images from the pipeline. See Convert-JpgToPdf.Tests.ps1 for all the tests.

Mocks, mocks, mocks, baked beans and mocks

There are other ways to achieve similar results. When I first wrote these tests I didn’t have the 6 stub functions. Instead I added the fake $doc to a script: scoped array each time I created it and in the It, I looped over it to make sure they were as expected. Sadly that didn’t work. I had a number of Write-Verbose statements, and I could see that they were being created and added but the array was empty when I checked it after.

A change in Pester 3.0 turned out the be the cause. From What’s New in Pester 3.0

“Tests.ps1 scripts are now executed in a separate scope than Pester’s internal code, preventing some types of bugs that would occur when a test script happened to define a function or variable name that matched something Pester uses internally (or mock calls to a function that Pester needs internally.)””

So the script: scope of my array was the issue. Not wanting to pollute my global scope restructured my tests to use all mocks instead.

Download the Script

Convert-JpgToPdf.ps1

Download the Tests

Convert-JpgToPdf.Tests.ps1

Testing Nirvana - 100% Code Coverage

Paul Vaillant — Fri, 22 May 2015 00:00:00 UTC

In my last post I introduced testing a PowerShell scripts, now lets take that a little deeper and improve on the testing.

“Improve on the testing” you say, “how is that possible?”

When you are testing a script, or function or any piece of code, you want to be sure not only to test the main path, the normal case, but all the different execution paths. Every if statement takes the execution through a different sequence and if there are some without test cases then you might have issues (that’s fancy for bugs) that are going to bite you later on.

There are a couple of different ways to go about doing this.

Test Driven Development

One option is to write your tests before you write your code (something called Test Driven Development or TDD). If you’re following this style of development then you’re creating a test before you even add a parameter or think about processing one kind of data differently. This option is also very good for the testability (that’s fancy for how easy it is to test) of your implementation because it forces you to find a way to test before you even start writing, rather than struggling to find a way to test something you’ve already written, and possibly having to go back and rewrite it to make it testable.

Code Coverage

Another option, which is particularly useful if you are writing your tests after the fact, is to use the Code Coverage feature of Pester. What is Code Coverage? Code coverage means what percentage of your code is covered by tests. A particular line of code is considered covered if it is executed by one or more test cases. Having 100% code coverage should be your ideal goal although sometimes it’s not possible. If you really aren’t able to achieve 100% code coverage you should be sure it’s for the right reasons and seriously consider if it may be because the implementation isn’t testable rather than the test case not being testable.

Dead Code

Code coverage, when you are using it after the fact, can also help discover dead code. I once read an article that software developer was a terrible term because it made it sound like there was a definate end. Instead, the article proposed the term software gardener because software can be very much like a living thing that grows but also needs pruning. When you have parts of your application that are no longer used, the right thing &trad; to do isn’t to leave them there but to remove them. Besides, if you ever needed them again, you could just checkout an older copy of your code from your SCM (you are using some kind of Revision Control tool like Git aren’t you?).

So How Did I Do?

A quick check of the code coverage of the tests from my last example shows less than 100%. Let’s dig into why.


PS> Invoke-Pester .\Get-PhoneNumberClass.Tests.ps1 -CodeCoverage .\Get-PhoneNumberClass.ps1

Code coverage report:
Covered 67.97 % of 128 analyzed commands in 1 file.

Missed commands:

File                     Function     Line Command
----                     --------     ---- -------
Get-PhoneNumberClass.ps1 ClassifySlow  156 Write-Verbose "Classifying $number (slow)"
Get-PhoneNumberClass.ps1 ClassifySlow  157 $class = "Ordinary"
Get-PhoneNumberClass.ps1 ClassifySlow  158 $reason = ""
Get-PhoneNumberClass.ps1 ClassifySlow  159 @("Gold","Silver","Bronze")
Get-PhoneNumberClass.ps1 ClassifySlow  159 "Gold","Silver","Bronze"
Get-PhoneNumberClass.ps1 ClassifySlow  160 $CLASSES[$c].GetEnumerator()
Get-PhoneNumberClass.ps1 ClassifySlow  160 foreach {...
Get-PhoneNumberClass.ps1 ClassifySlow  161 if($number -match $_.Value) {...
Get-PhoneNumberClass.ps1 ClassifySlow  162 $class = $c
Get-PhoneNumberClass.ps1 ClassifySlow  163 $reason = $_.Key
Get-PhoneNumberClass.ps1 ClassifySlow  168 @{Number = $number; Class = $class; Reason = $reason}
Get-PhoneNumberClass.ps1 ClassifySlow  168 Number = $number
Get-PhoneNumberClass.ps1 ClassifySlow  168 Class = $class
Get-PhoneNumberClass.ps1 ClassifySlow  168 Reason = $reason
Get-PhoneNumberClass.ps1               196 $numbers = 0..$RunSize | %{ Get-Random -Minimum 1991000000 -Maximum 99999...
Get-PhoneNumberClass.ps1               196 $numbers = 0..$RunSize | %{ Get-Random -Minimum 1991000000 -Maximum 99999...
Get-PhoneNumberClass.ps1               196 Get-Random -Minimum 1991000000 -Maximum 9999999999
Get-PhoneNumberClass.ps1               198 Measure-Command { foreach($n in $numbers) { ClassifyFast $n | out-null } }
Get-PhoneNumberClass.ps1               198 $numbers
Get-PhoneNumberClass.ps1               198 ClassifyFast $n
Get-PhoneNumberClass.ps1               198 out-null
Get-PhoneNumberClass.ps1               199 select @{n='Name';e={'Fast'}},TotalMilliseconds
Get-PhoneNumberClass.ps1               199 n = 'Name'
Get-PhoneNumberClass.ps1               199 e = {'Fast'}
Get-PhoneNumberClass.ps1               199 'Fast'
Get-PhoneNumberClass.ps1               201 Measure-Command { foreach($n in $numbers) { ClassifySlow $n | out-null } }
Get-PhoneNumberClass.ps1               201 $numbers
Get-PhoneNumberClass.ps1               201 ClassifySlow $n
Get-PhoneNumberClass.ps1               201 out-null
Get-PhoneNumberClass.ps1               202 select @{n='Name';e={'Slow'}},TotalMilliseconds
Get-PhoneNumberClass.ps1               202 n = 'Name'
Get-PhoneNumberClass.ps1               202 e = {'Slow'}
Get-PhoneNumberClass.ps1               202 'Slow'
Get-PhoneNumberClass.ps1               204 Measure-Command { foreach($n in $numbers) { ClassifySlowOptimized $n | ou...
Get-PhoneNumberClass.ps1               204 $numbers
Get-PhoneNumberClass.ps1               204 ClassifySlowOptimized $n
Get-PhoneNumberClass.ps1               204 out-null
Get-PhoneNumberClass.ps1               205 select @{n='Name';e={'Slow Optimized'}},TotalMilliseconds
Get-PhoneNumberClass.ps1               205 n = 'Name'
Get-PhoneNumberClass.ps1               205 e = {'Slow Optimized'}
Get-PhoneNumberClass.ps1               205 'Slow Optimized'

Right away I can see that this points to two sections in my script; section 1 is lines 156 - 168 (the function ClassifySlow) and section 2 is lines 196-205 (this is the part of PROCESS dealing with the -Test flag).

How to remedy this? I’ve got a couple options here. I could remove both sections, actually I could go further and remove the -Slow option as well. Since this would introduce an incompatible backwards change (you couldn’t call the script with -Test and get the behavior you currently expected) that would mean bumping this to version 2.0.0. If you’re unfamilar with versioning, I strongly recommend reading Semantic Versioning and following it as a standard. If you are familar with SemVer then you’ll have recognized this already. Another option would be to add test cases that covered both sections. And a third option would be a little of both. That’s actually the option I’m going to go for.

For section 1 I’m just going to remove it since that version of the Classify function was one I did purely to compare the performance of different approaches and the only place it’s used currently is by the -Test section. For section 2, I’ll add a test case to cover this function:


Context "When a performance test is specified" {
    $ExpectedAlgorithms = @("Fast", "Slow")
    It "returns a list of algorithms and their total milliseconds" {
        [array]$results = & $cmd -Test
        $results.Length | Should Be $ExpectedAlgorithms.Length
        foreach($algo in $ExpectedAlgorithms) {
            $r = $results | where Name -eq $algo
            # in the latest Pester this is the same as
            # $r | Should Exist
            $r | Should Not Be $null
            $r.TotalMilliseconds | Should Match "^\d+\.\d+$"
        }
    }
}

From a semantic versioning perspective, given that the output of -Test is an array of hashes with the algorithm name and a time taken, I interpret this to be a patch level change; a backwards compatible bug fix. If the output of -Test had been an object with each algorithm as a property like this:


PS> [pscustomobject]@{Fast = 0.234; Slow = 0.345; SlowOptimized = 0.456}

 Fast  Slow SlowOptimized
 ----  ---- -------------
0.234 0.345         0.456

Then that would have been a backwards incompatible change.

What’s The Coverage Now?

So with those changes, what’s the coverage look like?


PS> Invoke-Pester .\Get-PhoneNumberClass.Tests.ps1 -CodeCoverage .\Get-PhoneNumberClass.ps1

Code coverage report:
Covered 100.00 % of 106 analyzed commands in 1 file.

Now that’s what I want to see!

Testing Your PowerShell Scripts

Paul Vaillant — Mon, 18 May 2015 00:00:00 UTC

Continuing from the exciting week last week at Microsoft Ignite 2015 in Chicago, I have to say that one of the things I was most amazed with was Jeffery Snover’s announcement that the next version of Windows would ship with open-source software! I think secretly he was very thrilled by this as well because every session of his that I was in, I noted that he mentioned this over and over again. Maybe it’s not the open-source aspect that he was most interested in, rather what this software is.

Pester, the software included now with Windows 10, is a testing framework for PowerShell. Testing is a key part of software development, as any dev will tell you, and it make sense given Microsoft’s increased focus on making PowerShell dev friendly (see the class keyword as another great example of this). And making it dev friendly is a key part of the new push for DevOps in Windows.

A Pester Overview

So I thought I’d talk about how to test a PowerShell script using the example from my latest post Classifying Phone Numbers. The first thing you need to do is create a tests file. The convention here is to have the same file name but with a suffix of .tests.ps1 instead of .ps1. For example, for a script file called Get-PhoneNumberClass.ps1, the tests file would be called Get-PhoneNumberClass.Tests.ps1.

Next, let’s look inside this tests file:


$here = Split-Path -Parent $MyInvocation.MyCommand.Path
$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path).Replace(".Tests.", ".")
$cmd = "$here\$sut"

Describe "My-Script" {
  Context "...the name of my context..." {
    It "...does something..." {
      $result = & $cmd
      $result.Value | Should Be "my expected value"
    }
  }
}

This style of testing is referred to as Behavior driven development and abbreviated as BDD.

The idea is to look at it logically, 1. Describe: this is the high level thing (like a script or function) that’s being described (tested) 2. Context: a specific context, or scenario, within the larger system 3. It: a specific aspect or behavior within the context 4. Should: an expected result of the behavior

Get-PhoneNumberClass.Tests.ps1

Let’s take a look at some real-world tests. In my last post I created a script that would use regular expressions to classify phone numbers into Gold, Silver, Bronze and Ordinary classes based on how nice the number looks.

The first thing are the various test cases; you need to have some inputs and expected outputs that will help test the various paths within your script.


$TestCases = @(
    @{Number = 7000011222; Class = "Gold"; Reason = "doubleTriple"},
    @{Number = 7000033440; Class = "Gold"; Reason = "doubleDouble0"},
    @{Number = 7000005555; Class = "Gold"; Reason = "same4"},
    @{Number = 7000006660; Class = "Gold"; Reason = "triple0"},
    @{Number = 7000007890; Class = "Gold"; Reason = "sequential4"},
    @{Number = 7005242110; Class = "Silver"; Reason = "double0"},
    @{Number = 7005242007; Class = "Silver"; Reason = "bond"},
    @{Number = 7005223434; Class = "Silver"; Reason = "twoDigitPattern"},
    @{Number = 7005224511; Class = "Bronze"; Reason = "double"},
    @{Number = 7005242390; Class = "Bronze"; Reason = "endsIn0"},
    @{Number = 7002398201; Class = "Ordinary"; Reason = ""}
)

In this case there are a number of different kinds of number patterns that will trigger the different classes so I have included an example of each.

Next I want to make sure that if I pass a number on the command line, it returns the correct class.


Context "When numbers are passed by the command line" {
    It "identifies <Number> as <Class>" -TestCases $TestCases {
        param($Number, $Class, $Reason)

        $c = & $cmd -Number $Number
        $c | Should Be $Class
    }
}

Since there’s also a flag that will cause the script to return extra details, I want to make sure I test that as well.


Context "When numbers are passed by the command line with Details" {
    It "identifies <Number> as <Class> because of <Reason>" -TestCases $TestCases {
        param($Number, $Class, $Reason)

        $c = & $cmd -Number $Number -Details
        $c.Number | Should Be $Number
        $c.Class | Should Be $Class
        $c.Reason | Should Be $Reason
    }
}

Lastly, since my script can also takes input from the pipeline instead of the command line, I want to test that scenario too.


Context "When numbers are passed by the pipeline" {
    It "identifies <Number> as <Class> because of <Reason>" -TestCases $TestCases {
        param($Number, $Class, $Reason)

        $c = $Number | & $cmd
        $c.Number | Should Be $Number
        $c.Class | Should Be $Class
        $c.Reason | Should Be $Reason
    }

    It "identifies all numbers in the pipeline" {
        $results = $TestCases | %{ $_.Number } | & $cmd
        foreach($t in $TestCases) {
            $r = $results | ? Number -eq $t.Number
            #$r | Should Exist
            $r.Number | Should Be $t.Number
            $r.Class  | Should Be $t.Class
            $r.Reason | Should Be $t.Reason
        }
    }
}

Running Your Tests

Now that we have a test file created we need to run it. If you’re on Windows 10 then you can just run Invoke-Pester from the folder that has your tests file in it. If you’re not on Windows 10 then you’ll need to install Pester. Pester is a PowerShell modules so the easiest way is to download the latest release (3.3.8), unzip it and run:

Import-Module c:\path\to\pester-3.3.8\pester.psd1

Or you can also easily install it using Chocolatey since there is a Pester package.

Once that’s done you’ll be able to call Invoke-Pester. When you do, you should see something like the following:

PS C:\path\to\tests> Invoke-Pester
Describing Get-PhoneNumberClass
   Context When numbers are passed by the command line
    [+] identifies 7000011222 as Gold 82ms
    [+] identifies 7000033440 as Gold 22ms
    [+] identifies 7000005555 as Gold 20ms
    [+] identifies 7000006660 as Gold 19ms
    [+] identifies 7000007890 as Gold 19ms
    [+] identifies 7005242110 as Silver 21ms
    [+] identifies 7005242007 as Silver 24ms
    [+] identifies 7005223434 as Silver 21ms
    [+] identifies 7005224511 as Bronze 22ms
    [+] identifies 7005242390 as Bronze 23ms
    [+] identifies 7002398201 as Ordinary 24ms
   Context When numbers are passed by the command line with Details
    [+] identifies 7000011222 as Gold because of doubleTriple 63ms
    [+] identifies 7000033440 as Gold because of doubleDouble0 22ms
    [+] identifies 7000005555 as Gold because of same4 22ms
    [+] identifies 7000006660 as Gold because of triple0 23ms
    [+] identifies 7000007890 as Gold because of sequential4 23ms
    [+] identifies 7005242110 as Silver because of double0 22ms
    [+] identifies 7005242007 as Silver because of bond 21ms
    [+] identifies 7005223434 as Silver because of twoDigitPattern 22ms
    [+] identifies 7005224511 as Bronze because of double 23ms
    [+] identifies 7005242390 as Bronze because of endsIn0 22ms
    [+] identifies 7002398201 as Ordinary because of  22ms
   Context When numbers are passed by the pipeline
    [+] identifies 7000011222 as Gold because of doubleTriple 65ms
    [+] identifies 7000033440 as Gold because of doubleDouble0 271ms
    [+] identifies 7000005555 as Gold because of same4 26ms
    [+] identifies 7000006660 as Gold because of triple0 22ms
    [+] identifies 7000007890 as Gold because of sequential4 22ms
    [+] identifies 7005242110 as Silver because of double0 22ms
    [+] identifies 7005242007 as Silver because of bond 26ms
    [+] identifies 7005223434 as Silver because of twoDigitPattern 25ms
    [+] identifies 7005224511 as Bronze because of double 27ms
    [+] identifies 7005242390 as Bronze because of endsIn0 26ms
    [+] identifies 7002398201 as Ordinary because of  29ms
    [+] identifies all numbers in the pipeline 125ms
Tests completed in 2.42s
Passed: 34 Failed: 0 Skipped: 0 Pending: 0

Now, when you make changes to your scripts in the future, you’ll have confidence that you haven’t broken something that was working.

Classifying Phone Numbers

Paul Vaillant — Mon, 11 May 2015 00:00:00 UTC

What an exiting week last week. I was in Chicago for Microsoft Ignite 2015. I had the opportunity to attend several very interesting sessions as well as walk the expo floor and meet with other great people in the PowerShell and Skype for Business community.

You might also notice from the tags above that I’m going to start using the SkypeForBusiness instead of the Lync tag. Both tag pages cross link to each other so in case you end up in one, you’ll have a friendly reminder to check the other as well.

The Inspiration

One of the sessions I attended was called “Save Time! Automate Phone Number Management in Skype for Business” by @StaleHansen. It was a great talk and I encourage you to check it as since it talks about similar topics that I’ve spoken about and it mentions both my Managing Your Lync Phone Numbers and Keeping Lync Unassigned Numbers Updated posts.

In this talk, he spoke about classifying numbers to keep nice numbers for certain use cases (IVRs, main numbers, senior executives, etc). There was an excellent slide that had rules he proposed:

In speak with him afterwards he mentioned that he hadn’t had time yet to implement the classification using regular expressions and I offered to help.

The Regular Expressions

I’ve created the following script to take a number and return a classification of Gold, Silver, Bronze or Ordinary based on his rules plus one more of my own (Silver numbers can have repeated patterns, like ending in 1212). It uses the following regular expressions to classify the numbers

Class	Reason	RegEx
Gold	Double Triple	(\d)\1(\d)\2{2}$
Gold	Double Double 0	(\d)\1(\d)\2{1}0$
Gold	Triple 0	(\d)\1{2}0$
Gold	Same 4	(\d)\1{3}$
Gold	Sequential 4	(?:0(?=1)\|1(?=2)\|2(?=3)\|3(?=4)\|4(?=5)\|5(?=6)\|6(?=7)\|7(?=8)\|8(?=9)\|9(?=0)){3}\d$
Silver	Double 0	(\d)\1{1}0$
Silver	James Bond	007$
Silver	Two Digit Pattern	(\d{2})\1$
Bronze	Double	(\d)\1$
Bronze	Ends in 0	0$

Anything else is classified as Ordinary.

A couple quick notes on the regular expressions:

$ matches the end of the line
\d matches any number
* means match the preceding item 0 or more times
? means match the preceding item 0 or 1 times
- means match the preceding item 1 or more times
{#} means match the preceding item exactly # times
any statement within () creates a capture group with some exceptions
- if the capture group starts with ?: that means don’t capture
- (?x) isn’t a capture group but says the regular expression should ignore comments and unescaped whitespace; this makes large complex expressions more readable
- (?=…) means match as long as the next item matches the group …, but it doesn’t capture this next item
groups can have multiple options separated by
\1 (or any \#, etc) matches the 1st (or #th) capture group

You may have noticed that I used {1} in some of the regular expressions. You don’t normally need to do this (the default is to match one), but I do this when I want to match 0 afterwards since I need to break up the numbers, otherwise if I wrote (\d)\10 (for example) it would want to match a digit followed by the value of the 10th capture group. This could be written other ways, like (\d)\1[0] or (\d)\1(?:0) or even (\d)\1 0 (if you’re using (?x)), all of which are identical.

The Complicated One

The Sequential 4 is probably the most complex so I’ll take a moment to describe it.

(?:
    0(?=1)| # match a 0 as long as a 1 comes after
    1(?=2)| # match a 1 as long as a 2 comes after
    2(?=3)| # match a 2 as long as a 3 comes after
    3(?=4)| # match a 3 as long as a 4 comes after
    4(?=5)| # match a 4 as long as a 5 comes after
    5(?=6)| # match a 5 as long as a 6 comes after
    6(?=7)| # match a 6 as long as a 7 comes after
    7(?=8)| # match a 7 as long as a 8 comes after
    8(?=9)| # match a 8 as long as a 9 comes after
    9(?=0)  # match a 9 as long as a 0 comes after
){3} # do that 3 times
\d   # and also capture the last digit

So the only way for it to be able to capture a 2 (for example) is if a 3 comes next. If that’s the case then it would also match the 3, but only if a 4 came next, and so on. It has to do this 3 times, which means there have to be 4 sequential numbers. Because the look forward ?= doesn’t capture that digit it ensured was there, I’ve included a \d at the end to capture it.

Slow and Fast

Some of these regular expressions are a little complex so I’ve implemented it two ways so that people can see different ways it could be done.

The first way is using an array simple regular expressions that are tested one after another.


$CLASSES = @{
    Gold = @{
        doubleTriple = "(\d)\1(\d)\2{2}$";
        doubleDouble0 = "(\d)\1(\d)\2{1}0$";
        triple0 = "(\d)\1{2}0$";
        same4 = "(\d)\1{3}$";
        sequential4 = "(?:0(?=1)|1(?=2)|2(?=3)|3(?=4)|4(?=5)|5(?=6)|6(?=7)|7(?=8)|8(?=9)|9(?=0)){3}\d$"
    };
    Silver = @{
        double0 = "(\d)\1{1}0$";
        bond = "007$";
        twoDigitPattern = "(\d{2})\1$"
    };
    Bronze = @{
        double = "(\d)\1$";
        endsIn0 = "0$"
    }
}

function ClassifySlow($number) {
    Write-Verbose "Classifying $number (slow)"
    $class = "Ordinary"
    $reason = ""
    foreach($c in @("Gold","Silver","Bronze")) {
        $CLASSES[$c].GetEnumerator() | foreach {
            if($number -match $_.Value) {
                $class = $c
                $reason = $_.Key
                break
            }
        }
    }
    @{Number = $number; Class = $class; Reason = $reason}
}

The second is by combining all of the regular expressions together and allowing the regular expression engine to optimize the parsing.


$CLASS_RE = "(?x)
(?:
    (?<Gold_doubleTriple>(\d)\1(\d)\2{2})
    |
    (?<Gold_doubleDouble0>(\d)\3(\d)\4 0)
    |
    (?<Gold_triple0>(\d)\5{2}0)
    |
    (?<Gold_same4>(\d)\6{3})
    |
    (?<Gold_sequential4>(?:0(?=1)|1(?=2)|2(?=3)|3(?=4)|4(?=5)|5(?=6)|6(?=7)|7(?=8)|8(?=9)|9(?=0)){3}\d)
    |
    (?<Silver_double0>(\d)\7 0)
    |
    (?<Silver_bond>007)
    |
    (?<Silver_twoDigitPattern>(\d{2})\8)
    |
    (?<Bronze_double>(\d)\9)
    |
    (?<Bronze_endsIn0>0)
)$"

function ClassifyFast($number) {
    Write-Verbose "Classifying $number (fast)"
    $class = "Ordinary"
    $reason = ""
    if($number -match $CLASS_RE) {
        $class,$reason = $($matches.Keys | ? { $_ -notmatch "^[0-9]+$" }) -split '_'
    }
    @{Number = $number; Class = $class; Reason = $reason}
}

Since these two alternate methods are driven by performance, I’ve included a -Test flag you can use to experience the differences between the two. In test runs on my computer, the normal fast option using the combined all-in-one regex runs about 3x faster than the slow option. There are some additional optimizations that make it possible for the slow option to run similar to the fast option but the it requires unwinding the nicely maintainable hash into arrays and using 53 lines instead of 10. Actually the code difference is event larger when you take into consideration that the all-in-one regular expression really is just 2 core lines of if(-match) and finding and splitting out the class and reason from the group capture name.

Get-PhoneNumberClass.ps1

Coming up next is testing scripts with Pester. If you want a sneak peak, checkout the test script for this script here: Get-PhoneNumberClass.Tests.ps1.

Document Your PowerShell Scripts

Paul Vaillant — Fri, 01 May 2015 00:00:00 UTC

I was inspired by old war posters with this title. Can’t you picture the classic Uncle Sam with his finger out and a caption that reads “I want YOU to document your scripts!”? Or maybe you could twist it a different way and it would be motivational poster with the kitten running thought the fields captioned with “every time you release a script without documentation, a kitten dies” (it’s a thing they tell me).

Today we’re talking about documenting PowerShell scripts. I love that you can embed the documentation directly into the script and that Get-Help formats it all for you and makes it nice.

Quick tip #1: you can access the help by adding -? to the end of any cmdlet. EG Get-Command -?

Quick tip #2: if you’re coming from the Unix world, fear not. Microsoft has created an alias ‘man’ for Get-Help so everything is as it should be.

The inline documentation takes the form of a comment block (I like to use <# and #>, but you can just comment every line starting with # if you want) at the start of the file. Then within that block you can specify different pieces of information including:

.SYNOPSIS – a brief explanation of what the script or function does
.DESCRIPTION – a more detailed explanation of what the script or function does
.PARAMETER <name> – an explanation of a specific parameter. You should have have one of these sections for each parameter the script or function uses.
.EXAMPLE – an example of how to use the script or function. You can have multiple .EXAMPLE sections if you want to provide more than one example.
.INPUTS - Description and types of objects that can be piped to the function or script
.OUTPUTS - Description and type of the objects that the cmdlet returns
.NOTES – any miscellaneous notes on using the script
.LINK – If you include a URL beginning with http:// or https://, it will be opened automatically when Get-Help is called with –online

You can get more details in about Comment Based Help (or by running Get-Help about_Comment_Based_Help). There’s also another good reference on MSDN How to Write Cmdlet Help.

So this is to say that I’m doing my part to save the kittens. All the scripts on my site now include documentation. You can check it out in my new Get-Help section. I also created a tool, well a PowerShell script, called ConvertTo-HelpMarkdown that will read out the inline documentation and create a markdown page that, as in my case, can be converted to HTML. You can download it from my scripts page if you’d like.

Installing LRS Admin The Easy Way

Paul Vaillant — Fri, 24 Apr 2015 00:00:00 UTC

Maybe that should be The Easy Way ™? Oh, it’s probably too generic to trademark anyways. Besides, by now I’m sure you know what my easy way is don’t you? If you guessed anything other than PowerShell then I’m sad and you should spend more time reading my other blog posts.

I really love Lync Room Systems. Not the blind-for-no-reason kind of love, the customers-see-and-experience-ROI-so-easily kind of love which is also the first-hand-makes-my-life-easier-and-better kind of love if you have ever used an LRS. “Start meetings faster” seems like such a simple value proposition but it’s so powerful. Anyway, love of LRS aside, if you have any LRS then you should also be using the LRS admin tool. Unfortunately this isn’t built into Lync but there are some fairly details deployment instructions if you’re into that whole RTFM. Puff… why read a manual on how to deploy something when someone else has written a script to do all that! Well that’s what I’ve done for you.

I’ll post the link for this script right here in case people don’t want to go any further.

Install-LrsAdmin.ps1

For those of you who are interested, thanks for continuing to read .

There are a number of parameters that you can specify but they all have defaults.


param(
	[Parameter()][string]$LrsAppUser = "LRSApp",
	[Parameter()][string]$LrsAppUserOU = "CN=Users",
	[Parameter()][string]$LrsSupportAdminGroup = "LRSSupportAdminGroup",
	[Parameter()][string]$LrsSupportAdminGroupOU = "CN=Users",
	[Parameter()][string]$LrsFullAccessAdminGroup = "LRSFullAccessAdminGroup",
	[Parameter()][string]$LrsFullAccessAdminGroupOU = "CN=Users",
	[Parameter()][string]$PoolName,
	[Parameter()][string]$SipDomain
)

For $PoolName and $SipDomain, if they aren’t specified the script tries to auto-detect a value.


if(!$PoolName) {
	Write-Verbose "Auto-detecting Lync Pool..."
	[array]$registrars = Get-CsService -Registrar -Verbose:$false
	if($registrars.count -eq 1) {
		$PoolName = $registrars[0].PoolFQDN
		Write-Verbose "    found $PoolName"
	} else {
		$pools = $($registrars | %{ $_.PoolFQDN }) -join " "
		Write-Error "Failed to auto-detect registrar pool; please specify LyncRegistrarPool and try again [$pools]"
		exit
	}
}

if(!$SipDomain) {
	Write-Verbose "Auto-detecting SIP Domain..."
	$sipDomains = Get-CsSipDomain -Verbose:$false
	if(!$sipDomains -or $sipDomains -is [array]) {
		Write-Error "Failed to auto-detect proper SIP domain"
		exit
	} else {
		$SipDomain = $sipDomains.Name
		Write-Verbose "    found $SipDomain"
	}
}

Then we check that the script is being run on a Lync Front End with at least CU2.


$fe = Get-WmiObject -query 'select * from win32_product' | where {$_.name -like "Microsoft Lync Server 2013, Front End Server"}
if(!$fe) {
	Write-Error "This machine is not a Lync Front End"
	exit
}
$feVer = $fe.Version
[int]$feVerBuild = $feVer -split '\.' | select -last 1
if(!$feVer.StartsWith("5.0.8308.") -or $feVerBuild -lt 557) {
	Write-Error "Lync Front End is not minimum Lync 2013 CU2 (July/2013)"
	exit
}

The first step is to create a SIP enabled user for the app.


$appUser = Get-ADUser -filter {sAMAccountName -eq $LrsAppUser} -Verbose:$false # work around not supporting -ErrorAction SilentlyContinue
if($appUser) {
	Write-Warning "LRS App User $LrsAppUser already exists"
} else {
	$appUserOu = ToAbsoluteLdap $LrsAppUserOU
	$appUser = New-AdUser $LrsAppUser -GivenName LRS -Surname User -DisplayName $LrsAppUser -SamAccountName $LrsAppUser -Path $appUserOu -Server $dc -PassThru 
}
if(!$appUser) {
	Write-Error "Failed to create AD user $LrsAppUser"
	exit
}
$csUser = Get-CsUser $appUser.DistinguishedName -Verbose:$false -ErrorAction SilentlyContinue
if($csUser) {
	if($csUser.Enabled) {
		Write-Warning "LRS App User $LrsAppUser already enabled for Lync"
	} else {
		Write-Warning "LRS App User $LrsAppUser exists but is disabled for Lync"
	}
} else {
	$csUser = Enable-CsUser $appUser.DistinguishedName -RegistrarPool $PoolName -SipAddress "sip:$LrsAppUser@$SipDomain" -DomainController $dc -PassThru
}
if(!$csUser) {
	Write-Error "Failed to SIP enable LRS App User $LrsAppUser"
	exit
}

The second step is to create the global security groups in AD.


$supportAdminsGrp = Get-ADGroup -filter {sAMAccountName -eq $LrsSupportAdminGroup} -Verbose:$false # because no -ErrorAction SilentlyContinue
if($supportAdminsGrp) {
	Write-Warning "LRS Support Admin Group $LrsSupportAdminGroup already exists"
} else {
	$supportAdminsGrpOu = ToAbsoluteLdap $LrsSupportAdminGroupOU
	$supportAdminsGrp = New-ADGroup $LrsSupportAdminGroup -GroupScope Global -GroupCategory Security -SamAccountName $LrsSupportAdminGroup -Path $supportAdminsGrpOu -Server $dc -PassThru
}
if(!$supportAdminsGrp) {
	Write-Error "Failed to create AD group $LrsSupportAdminGroup"
	exit
}

$fullAdminsGrp = Get-ADGroup -filter {sAMAccountName -eq $LrsFullAccessAdminGroup} -Verbose:$false # because no -ErrorAction SilentlyContinue
if($fullAdminsGrp) {
	Write-Warning "LRS Full Access Admin Group $LrsFullAccessAdminGroup already exists"
} else {
	$fullAdminsGrpOu = ToAbsoluteLdap $LrsFullAccessAdminGroupOU
	$fullAdminsGrp = New-ADGroup $LrsFullAccessAdminGroup -GroupScope Global -GroupCategory Security -SamAccountName $LrsFullAccessAdminGroup -Path $fullAdminsGrpOu -Server $dc -PassThru
}
if(!$fullAdminsGrp) {
	Write-Error "Failed to create AD group $LrsFullAccessAdminGroup"
	exit
}

$supportAdminsGrpMbrs = $supportAdminsGrp | Get-AdGroupMember | %{ $_.distinguishedName }
if(-not $($supportAdminsGrpMbrs -contains $fullAdminsGrp.distinguishedName)) {
	Write-Verbose "Adding LRS Full Access Admin Group as member of LRS Support Admin Group"
	Add-ADGroupMember $supportAdminsGrp.distinguishedName $fullAdminsGrp.distinguishedName -Server $dc
} else {
	Write-Warning "LRS Full Access Admin Group is already a member of LRS Support Admin Group"
}

The third step is to install ASP.NET MVC 4.


$aspMvc4 = Get-WmiObject -Class Win32_Product | where {$_.Name -eq 'Microsoft ASP.NET MVC 4 Runtime'}
if($aspMvc4) {
	Write-Warning "ASP.NET MVC 4 Runtime is already installed"
} else {
	$url = "http://download.microsoft.com/download/2/F/6/2F63CCD8-9288-4CC8-B58C-81D109F8F5A3/AspNetMVC4Setup.exe"
	DownloadAndInstall $url
	$aspMvc4 = Get-WmiObject -Class Win32_Product | where {$_.Name -eq 'Microsoft ASP.NET MVC 4 Runtime'}
}
if(!$aspMvc4) {
	Write-Error "Failed to install ASP.NET MVC 4 Runtime"
	exit
}

NOTE: the snippet above refers to a function DownloadAndInstall that is defined in the script file you can download but that I haven’t shown in the post. Download the script and use that if you want to copy and paste step by step.

The fourth step is to set the application ports.


Set-CsWebServer -Identity $PoolName `
		-MeetingRoomAdminPortalInternalListeningPort 4456 `
		-MeetingRoomAdminPortalExternalListeningPort 4457

$webSrv = Get-CsService -WebServer -PoolFqdn $PoolName
if($webSrv.MeetingRoomAdminPortalInternalListeningPort -ne 4456) {
	Write-Error "Failed to set MeetingRoomAdminPortalInternalListeningPort"
	exit
}
if($webSrv.MeetingRoomAdminPortalExternalListeningPort -ne 4457) {
	Write-Error "Failed to set MeetingRoomAdminPortalExternalListeningPort"
	exit
}

The fifth step is to actually download and install the LRS Admin app.


$url = "http://download.microsoft.com/download/8/7/8/878DA290-F608-4297-B1C7-4A5FC8245EA3/LyncRoomAdminPortal.exe"
DownloadAndInstall $url
if(-not $(Test-Path $installPath)) {
	Write-Error "Failed to install Lync Room Admin Portal"
	exit
}

Then finally the last step is to write the web.config file for the app.


$webConfig = "$installPath\web.config"
$cfgOrig = ''
$cfgNew = '<add key="PortalUserName" value="sip:' + $LrsAppUser + "@" + $SipDomain + '" />' + "`n" +
	'    ' + "`n" +
	'    '
$(gc $webConfig) -replace $cfgOrig,$cfgNew | Out-File $webConfig -Encoding ASCII

Now wasn’t that easier then doing it all by hand?

Managing extensions in Lync dial plans

Paul Vaillant — Fri, 17 Apr 2015 00:00:00 UTC

The title of this article should probably include the works “without having to tear your hair out”. Extensions are one of those things that are synonymous with PBX for a lot of people. And extensions are something that also can be a point of frustration with Lync, not only because of how they are managed, but also with the duplication that can occur given that extensions have to be separately entered into Lync and Exchange. Well here’s some PowerShell to make your day better if you deal with extensions.

First some context: this script was developed while working with a customer who wanted to have both DIDs as well as maintain legacy extensions. It was developed to make the extensions more manageable since the same effort could have been achieved manually at the cost of less hair at the end of the day or whenever a change was required (add extension, change extension, etc).

Second, a little segway first into E.164 and RFC3966. This are the relevant standards for the tel: URI used in Lync for the LineURI value assigned to a user. I like standards and for DIDs that means tel:+17005551212 all the time. In this case what we’re adding is the extension for each user to the LineURI itself in the form of tel:+17005551212;ext=1234. If you’re interested in E.164 and Lync I’d suggest also reading a nice post by Ken Lasko on the subject of how to format service numbers (Service Number Formatting in Lync).

Now to the script! First we grab all the users.

$users = Get-CsUser -Filter {EnterpriseVoiceEnabled -eq $true}

Then we make sure that the same extension hasn’t been assigned more than once (it happens, easily, hence the check).


$assignedDups = new-object 'system.collections.generic.dictionary[int,system.collections.generic.list[string]]'
$assignedExts = new-object 'system.collections.generic.dictionary[int,string]'
# for every user who has an extension assigned
$users | where LineURI -match ';ext=' | foreach {
	$sip = $_.SipAddress
	$line = $_.LineURI.Substring(4) # remove tel:
	[int]$ext = $line -split ';ext=' | select -last 1
	# check if we've seen this extension already
	if($assignedDups.ContainsKey($ext)) {
		# seen this before multiple times
		$assignedDups[$ext].Add($line)
	}
	else if($assignedExts.ContainsKey($ext)) {
		# this is the second time we've seen this extension
		# create a list of duplicates; the first one and this one
		$dups = new-object 'system.collections.generic.list[string]' @($assignedExts[$ext],$line)
		# save the duplicates
		$assignedDups.Add($ext, $dups)
		# and remove this extension from the unique list
		$assignedExts.Remove($ext)
	}
	else {
		# this is the first time we've seen this extension
		$assignedExts.Add($ext, $line)
	}
}

# if we've seen any duplicates
if($assignedDups.Count -gt 0) {
	# for each duplicate
	$assignedDups.GetEnumerator() | foreach {
		# print a warning that shows all the phone numbers assigned this duplicate
		$dups = $_.Value -join ', '
		Write-Warning "Skipping $($_.Key) which has duplicates ($dups)" 
	}
}

Once we have a list of extensions that aren’t duplicates it’s just a matter of getting all the dial plan normalization rules and checking for any rules that are missing.


$rules = Get-CsVoiceNormalizationRule -Identity $DialPlan | where Name -match $NormalizationRulePrefix
$currentExts = new-object 'system.collections.generic.dictionary[int,string[]]'
$rules | foreach {
	[int]$ext = $_.Pattern.Substring(1, $_.Pattern.Length - 2) # remove leading ^ and trailing $
	$line = $_.Translation
	$identity = $_.Identity
	$currentExts.Add($ext, [string[]]@($line,$identity))
}

$assignedKeys = $assignedExts.Keys
$currentKeys = $currentExts.Keys

# adds = assigned keys - current keys
$newExts = $assignedKeys | where { $currentKeys -notcontains $_ }
Write-Verbose "$($newExts.count) new extensions"

# deletes = current keys - assigned keys
$oldExts = $currentKeys | where { $assignedKeys -notcontains $_ }
Write-Verbose "$($oldExts.count) old extensions"

# updates = existing current keys that don't match assigned keys
$setExts = $assignedKeys | where { $currentKeys -contains $_ -and $assignedExts[$_] -ne $currentKeys[$_][0] }
Write-Verbose "$($setExts.count) updated extensions"

I do this because I expect this script to be run over and over and it wouldn’t make sense to recreate the dial plan from scratch each time when we can just make the small number of changes that will happen, if any, between runs. The most likely scenario is that we there’s only a small number of adds/changes each time.

Now that we know the changes we need to make, make them!


$batch = Get-Date -Format "yyyy-MM-dd HH:mm"

# new-csvoicenormalizationrule w/ date as description
$newExts | foreach {
	New-CsVoiceNormalizationRule -Identity "$DialPlan/$NormalizationRulePrefix $_" -Pattern $('^' + $_ + '$') -Translation $assignedExts[$_] -Description "Created $batch" -Confirm:$false
}

# set-csvoicenormalizationrule w/ date as description
$setExts | foreach {
	$rule = $currentKeys[$_][1]
	Set-CsVoiceNormalizationRule -Identity $rule -Translation $assignedExts[$_] -Description "Updated $batch" -Confirm:$false
}

# remove-csvoicenormalizationrule
$oldExts | foreach {
	$rule = $currentKeys[$_][1]
	Remove-CsVoiceNormalizationRule -Identity $rule -Confirm:$false
}

If you have the need to manage extensions, download this script today!

Update-LyncExtensionDialing.ps1

Keeping Lync Unassigned Numbers Updated

Paul Vaillant — Fri, 10 Apr 2015 00:00:00 UTC

Here’s a perfect example of something a human should never half to do: maintain a list of unassigned phone numbers. The only problem is where to get an authoritative source of the numbers that are in Lync? Hmmm… we could use an Excel spreadsheet but that just moves the burden of suffering to maintaining the spreadsheet instead of removing it. Instead of doing that by hand, let’s use the uControl API I talked about earlier (see Managing Your Lync Phone Numbers) and some PowerShell.

The first thing we need to do is get a list of all the phone numbers on the SIP trunk. Using the uControl RESTful API:


$wc = New-Object System.Net.WebClient
$wc.Credentials = $Credential.GetNetworkCredential()
$sipTrunkDidsUrl = "https://api.thinktel.ca/REST.svc/SipTrunks/{0}/Dids?PageFrom=0&PageSize=100000" -f $SipPilotNumber
$didsXml = $wc.DownloadString($sipTrunkDidsUrl)
if(-not $didsXml) {
	Write-Error "Failed to list DIDs on SIP Pilot $SipPilotNumber"
	exit
}
$didsList = [xml]$didsXml
if(-not $didsList -or -not $didsList.ArrayOfTerseNumber) {
	Write-Error "Failed to load or parse DIDs on SIP Pilot $SipPilotNumber"
	exit
}
$didsList.ArrayOfTerseNumber.TerseNumber | %{ $_.Number }

With those in hand, let’s get all the current unassigned numbers:


Get-CsUnassignedNumber | %{
  [long]$start = $_.NumberRangeStart.Substring(2)
  [long]$end = $_.NumberRangeEnd.Substring(2)
  $start..$end
}

Lastly, let’d assume that there is already an announcement available for the unassigned numbers, so you can get it with Get-CsAnnouncement. Or, if you didn’t have an announcement, you could create one as follows:


New-CsAnnouncement -identity $(Get-CsService -ApplicationServer | select -first 1).identity `
  -Name "Unassigned" -Language en-us `
  -TextToSpeechPrompt "The number you're trying to reach is unassigned. Please try again"

With all that information, it’s just a little set math to find the entries we need to add and remove.

Like always, you can download this script

Update-LyncUnassignedNumbers.ps1

Keep in mind that because unassigned numbers are processed last in the Lync routing, we don’t have to worry about removing an unassigned number if you assign it to a user or contact in Lync. If you really want to, say because you really want to keep your unassigned numbers purely for unassigned numbers, take solace: you are not alone. There is an option in the script above (-Force) that will do just that.

Alternative to Export-CsArchivingData

Paul Vaillant — Thu, 02 Apr 2015 00:00:00 UTC

Have you heard about the Lync Archiving role? If not, it’s the compliance and e-discovery component of Lync. It’s similar to the litigation hold functionality available in Exchange. You configure archiving with a number of policy options like whether to notify federated partners of the archiving, retention period, archiving requirement (eg block msgs if they can’t be archived), etc. Refer to the documentation for Set-CsArchivingConfiguration for a more complete list of the settings.

It’s also important to understand what archiving stores and what it doesn’t. It stores instant messages, either P2P or in conferences but nothing else. No files transferred, no audio, no video nor screensharing.

Archiving should also not be confused with conversation history. Conversation history is stored in Exchange and is what users access as their record of the conversation. It can also be deleted by the end user themselves which is not desirable for archiving.

Once you’ve got it configured and running it just works away in the background, but when you need to access it, then what? This is where Export-CsArchivingData comes in. You specify a database & output folder plus optionally a start/end date & user URI, and it creates multiple Outlook Express Electronic Mail (EML) file (.EML file extension) in the output folder. That’s ok, but what if you want something different? SQL to the rescue!

Archiving is stored in the LcsLog database. Sadly there’s no schema documentation available on TechNet but you can use the following query to get messages that a person either sent or got. It works in both Lync 2010 and Lync 2013.


use LcsLog
declare @start datetime = '2015-01-01 00:00:00'
declare @end datetime = '2015-01-31 00:00:00'
declare @useruri nvarchar(max)

select
	m.MessageIdTime Time, f.UserUri FromUser, t.UserUri ToUser, 'p2p' Type, ct.ContentType, m.Body
from Messages m
	join Users f on m.FromId = f.UserId
	join Users t on m.ToId = t.UserId
	join ContentTypes ct on m.ContentTypeId = ct.ContentTypeId
where
	m.MessageIdTime >= @start and m.MessageIdTime < @end
	and (@useruri is null or (f.UserUri = @useruri or t.UserUri = @useruri))
UNION ALL
select
	m.Date Time, f.UserUri FromUser, t.UserUri ToUser, 'conference' Type, ct.ContentType, m.Body
from ConferenceMessages m
	join Users f on m.FromId = f.UserId
	join ConferenceMessageRecipientList rl on rl.MessageId = m.MessageId
	join Users t on rl.UserId = t.UserId
	join ContentTypes ct on m.ContentTypeId = ct.ContentTypeId
where
	m.Date >= @start and m.Date < @end
	and (@useruri is null or (f.UserUri = @useruri or t.UserUri = @useruri))
order by Time

Substitute your desired date range, bearing in mind that the time is in UTC and optionally specify a @useruri in the form of user@domain.com.

The P2P messages are fairly straight forward but the conference is a little quirky. That’s because of the way conference participants are stored. As such, you need to join the conferences tables with the participants table and the conference messages table to get all the information. This query will cause the query to take a little while to return data if no @useruri is specified.

Last note, since this is in the LcsLog database, you’ll need to run this as a user in RTCComponentUniversalServices or another group with specific access to the SQL instance or that database.

You can also use the same PowerShell technique as in Last Login for a SIP URI to run this via PowerShell.

Find That Troublesome Wi-Fi AP

Paul Vaillant — Fri, 27 Mar 2015 00:00:00 UTC

Soft clients are one of the best things about VoIP phone systems and the Lync client is no exception. Being able to have everything on one device gives the solution such portability and mobility. Most of the time this mobility, at least within an office environment, is also made possible because of WiFi.

Fun fact, when Lync 2010 was released, voice and video over WiFi wasn’t officially support (well voice/video weren’t validated over Wi-Fi). I’m sure that didn’t stop people from doing it anyway but its still a fun fact.

Along came Lync 2013 with support, and in also the Lync SDN API which made it even better. Well does it? The Lync SDN API is great as long as you have either an HP, or an ~~aruba~~HP, Wi-Fi network, but what if you have something else? QoEMetrics to the rescue!

Part of the data that Lync sends to QoE is the BSSID of the wireless access point that its connected to. You can use this data to group together all the calls that went through each access point in your network. In addition, because of the way the data is stored, you can distinguish inbound and outbound streams. You would think this makes a difference but it does.

I wrote this query while working with a customer who was getting reports of call problems that seemed overwhelming. We started by grouping the QoE reports by logical site and quickly realized that one site only seemed to be having problems. When we first dug into that site there didn’t seem to be a pattern until finally we grouped by BSSID and the pieces fell into place. Backed with this data that showed two APs as the common factor the problem was quickly resolved.


use QoEMetrics;

declare @endtime datetime = CURRENT_TIMESTAMP;
declare @begintime datetime = DATEADD(day, -7, @endtime);

declare @SitePrefixes table (prefix nvarchar(max) COLLATE Latin1_General_CI_AI, name nvarchar(max) COLLATE Latin1_General_CI_AI);
insert into @SitePrefixes values ('10.10.%','Edmonton'), ('10.20.%','Toronto'), ('10.0.%','Datacenter');

with cdrs as (
	Select
		CallerSubIp.IpAddress CallerSubnet, CalleeSubIp.IpAddress CalleeSubnet, 
		callerBssid.MacAddress CallerBssid, calleeBssid.MacAddress CalleeBssid, 
		a.SenderIsCallerPAI AudioSenderIsCallerPAI,
		a.PacketLossRate*100.0 AudioPktLossRatePct, a.PacketLossRateMax*100.0 AudioPktLossRateMaxPct
	FROM 
		Session s
		inner join MediaLine m on s.ConferenceDateTime = m.ConferenceDateTime and s.SessionSeq = m.SessionSeq
		left join AudioStream a on 
			m.ConferenceDateTime = a.ConferenceDateTime and m.SessionSeq = a.SessionSeq and m.MediaLineLabel = a.MediaLineLabel
		left join dbo.IpAddress CallerSubIp on m.CallerSubnet = CallerSubIp.IpAddressKey
		left join dbo.IpAddress CalleeSubIp on m.CalleeSubnet = CalleeSubIp.IpAddressKey
		left join MacAddress callerBssid on m.CallerBssid = callerBssid.MacAddressKey
		left join MacAddress calleeBssid on m.CalleeBssid = calleeBssid.MacAddressKey
	Where 
		((callerBssid.MacAddress is not null or calleeBssid.MacAddress is Not null)) and 
		s.ConferenceDateTime >= @begintime and s.ConferenceDateTime < @endtime
), subnets as (
	select 
		case 
			when p.name is null then s.Subnet
			else p.name
		end as Site,
		s.Subnet
	from
		(select distinct CallerSubnet Subnet from cdrs
		 UNION
		 select distinct CalleeSubnet Subnet from cdrs) s
		left join @SitePrefixes p on s.Subnet like p.prefix
)

select 
	callerSub.Site CallerSubnet, CallerBssid, calleeSub.Site CalleeSubnet, CalleeBssid, 
	case
		when AudioSenderIsCallerPAI = 1 then 'caller-to-callee'
		else 'callee-to-caller'
	end as Direction, count(*) cnt,
	min(AudioPktLossRatePct) MinPktLossPct, avg(AudioPktLossRatePct) AvgPktLossPct, max(AudioPktLossRatePct) MaxPktLossPct,
	min(AudioPktLossRateMaxPct) MinPktLossMaxPct, avg(AudioPktLossRateMaxPct) AvgPktLossMaxPct, max(AudioPktLossRateMaxPct) MaxPktLossMaxPct
from cdrs
	join subnets callerSub on CallerSubnet = callerSub.Subnet
	join subnets calleeSub on CalleeSubnet = calleeSub.Subnet
where AudioPktLossRatePct is not null
group by callerSub.Site, CallerBssid, calleeSub.Site, CalleeBssid, AudioSenderIsCallerPAI having count(*) > 5
order by avg(AudioPktLossRatePct) desc

This query returns caller/callee site & access point MAC address, direction of the audio stream (remember there are 2 for each call, caller -> callee and callee -> caller) along with min/average/max packet loss percentages. There’s actually 2 sets of packet loss stats, one is over the average over the whole of the stream and the second is the max of the packet loss samples over the individual streams. The second is important because not all calls are all bad; calls can also have periods of packet loss which result in audio quality problems that end users are just as ready to describe as a ‘bad call’ as a call where the whole call suffers from packet loss.

This query makes extensive use of common table expressions to keep everything clean. You can adjust the date range if you want something other than the last 7 days but I find any more than this problems don’t stand out and any less you’re likely to miss non-persistent issues. Also add IP patterns for your sites (in the insert into @SitePrefixes line instead of the 3 sample values I have) and the results at the end will be labeled with your site names instead of subnets. Keep in mind these are SQL patterns so % is the wildcard character.

Create a Report of Assigned Lync User Licensing

Paul Vaillant — Tue, 24 Mar 2015 00:00:00 UTC

I’ve talked about the importance of having data when making decisions before. Decisions isn’t the only thing data is good for. Another great us is checking to make sure things are as you expect them to be. So today we’re going to talk about licensing, specifically Lync user licensing. Lync licensing can be challenging because there is no magic check box in the product that correspond to the difference between a “Standard” and “Enterprise” CAL. Those features are governed by the conference policy assigned to the user. To complicate matters, that policy can be global, site or user scoped, so in some cases it may depend on what site the user is logged in at.

There is a reference from Microsoft available, the Lync pricing and licensing guide, that details the various features of each CAL. You can also consult the Microsoft Product Use Rights Document for further information.

Those are big docs, so I’ll summarize the differences between the two here.

STANDARD CAL

Presence & P2P IM/audio/video/file transfer (no application sharing or white boarding)
Multi-party IM and file transfer (can’t initiate audio or video)
Attend conferences as an attendee (not a presenter)

ENTERPRISE CAL

Ad-hoc multi-party meetings with audio and video, including PSTN dial out
P2P application sharing and white boarding
Scheduling & inviting attendees to meetings
Lync Room Systems

I’ve omitted the Plus CAL above for brevity since, unlike the Enterprise CAL, there’s a clear setting “Enterprise Voice Enabled” on the Lync user object.

So how do we check for this? We evaluate the conferencing policies in Lync to see if they properly limit the user to only the Standard CAL features.


$enterpriseConferencingPolicies = Get-CsConferencingPolicy | where {
	!$(!$_.AllowIPAudio -and !$_.AllowIPVideo -and !$_.AllowUserToScheduleMeetingsWithAppSharing -and
		!$_.AllowAnonymousParticipantsInMeetings -and !$_.AllowPolls -and 
		$_.EnableAppDesktopSharing -eq 'None' -and !$_.EnableDialinConferencing)
}

This looks for conferencing policies that allow for either audio or video, or scheduled meetings, or any of the other features listed above. Once we have this list, then we can evaluate all users to see if they are assigned on of these policies in order to determine what licensing they should have.


[array]$enterpriseConfPolicyIds = $enterpriseConferencingPolicies | %{ $_.Identity }
$assignedUserLicenses = Get-CsUser | foreach {
	$confPolicy = $($_ | Get-CsEffectivePolicy).ConferencingPolicy.ToString()
	[pscustomobject]@{
		user = $_; 
		lyncStandardCAL = $true; 
		lyncEnterpriseCAL = $enterpriseConfPolicyIds -contains $confPolicy; 
		lyncPlusCAL = $_.EnterpriseVoiceEnabled -or $_.RemoteCallControlTelephonyEnabled
	}
}

# we can get a nice summary by counting each license type
$sums = $assignedUserLicenses | measure lyncStandardCAL,lyncEnterpriseCAL,lyncPlusCAL
# and extracting it from the measure using group & select
$sums | group Property | select Name,@{n='Count';e={$_.Group[0].Count}}

In addition to the licensing for users, also keep in mind licensing for Lync Room Systems (Get-CsMeetingRoom) and also for common area phones (Get-CsCommonAreaPhone).

As an interesting side note, it’s also possible to perform the same check without using the Lync PowerShell cmdlets. You can get the SQL instance that stores the CMS (and the conferencing policies) by querying the configuration naming context of AD for (objectClass=msRTCSIP-GlobalTopologySetting) and reading the attribute msRTCSIP-BackEndServer. Then you can connect to the xds database in this SQL instance query it for:


SELECT Doc.Name,Item.Data FROM [Item] Item join Document Doc on Item.DocId = Doc.DocId where Doc.Name like '%MeetingPolicy%'

You can then deserialize the returned XML and you have exactly the same value as from Get-CsConferencingPolicy.

Lastly you can get all the Lync objects from Active Directory as well. I like to use the query (|(msRTCSIP-Line=*)(msRTCSIP-PrimaryUserAddress=*)) since it returns all Lync objects but you could further filter by objectClass if you wanted only users. The attribute msRTCSIP-UserPolicies (which is a multi-value attribute) contains values in the form of [policyNumber]=[policyID]. The [policyNumber] for the conferencing policy is 1 so you just need to find the value that start with 1=. If there isn’t one, then the global or site policy apply.

You can download a version I wrote in pure PowerShell that demonstrates this concept. The nice thing about PowerShell is that it’s so very close to .NET that it makes experimenting with things like this very easy. If anyone is interested let me know and maybe I’ll create a .NET library that does the above.

Get-LyncUserLicensing.ps1

Managing Your Lync Phone Numbers

Paul Vaillant — Wed, 18 Mar 2015 00:00:00 UTC

I love PowerShell! There, I said it, just in case anyone was wondering. I love that it let’s you dig in, mix and match data and get even more useful data out then what you started with. Case in point: I was working with a customer with a fairly large Lync deployment and a SIP trunk from ThinkTel who wanted to review the numbers they had on their SIP trunk and compare it to numbers assigned in Lync so they could identify any missing or available numbers. There are several example scripts around on how to do this. The key is that you have to pull from all the different kinds of objects that could be assigned phone numbers in Lync:


Get-CsUser -Filter {LineURI -ne $Null}
Get-CsUser -Filter {PrivateLine -ne $Null}
Get-CsAnalogDevice -Filter {LineURI -ne $Null}
Get-CsCommonAreaPhone -Filter {LineURI -ne $Null}
Get-CsRgsWorkflow | ?{ $_.LineURI }
Get-CsDialInConferencingAccessNumber -Filter {LineURI -ne $Null}
Get-CsExUmContact -Filter {LineURI -ne $Null}
Get-CsTrustedApplicationEndpoint -Filter {LineURI -ne $Null}
Get-CsMeetingRoom -Filter {LineURI -ne $Null}

I love RESTful APIs too! That’s the second part of this story. There’s a RESTful API for uControl, the ThinkTel web portal for managing SIP trunks, that let’s you get all of the DIDs on a SIP Trunk. Much easier than scraping a web page and trying to parse out the data from HTML.


$wc = New-Object System.Net.WebClient
$wc.Credentials = $(Get-Credential).GetNetworkCredential()
$sipTrunkDidsUri = "https://api.thinktel.ca/REST.svc/SipTrunks/{0}/Dids?PageFrom=0&PageSize=100000"
$sipTrunkDidsUrl = $sipTrunkDidsUri -f 7005551212
[xml]$didsXml = $wc.DownloadString($sipTrunkDidsUrl)
if($didsXml -and $didsXml.ArrayOfTerseNumber) {
	$didsXml.ArrayOfTerseNumber.TerseNumber | %{ $_.Number }
}

Replace 7005551212 in the example above with your own SIP trunk pilot number.

Now that we have all the assigned numbers and all the numbers on the trunk, it’s easy to loop through both and produce a list.

One more RESTful API while we’re at it; you can use Local Calling Guide to lookup the city for each of the numbers so that you can more easily find an available number for a new user based on where they need the number.


function LookupCity($tel) {
	$lcgUri = "http://www.localcallingguide.com/xmlprefix.php?npa={0}&nxx={1}"

	# we need a 10 digit number to extract the NPA/NXX from
	if($tel -match '^tel:+1(\d{10})(;ext=\d+)?$') {
		$tel = $tel = $tel.Substring(6,10)
	}
	if($tel -notmatch '^\d{10}$') {
		Write-Error "Couldn't identify NPA/NXX in $tel"
	}
	$npa = $tel.Substring(0,3)
	$nxx = $tel.Substring(3,3)

	if($npa -match "^8(00|88|77|66|55|44|33|22)$") {
		"Toll-free"
	} else {
		$lcgUrl = $lcgUri -f $npanxx.Substring(0,3),$npanxx.Substring(3,3)
		[xml]$lcgXml = $wc.DownloadString($lcgUrl)
		if($lcgXml -and $lcgXml.root.prefixdata) {
			$lcgXml.root.prefixdata.rc + ", " + $lcgXml.root.prefixdata.region
		} else {
			Write-Warning "Failed to identify city of $tel"
			"UNKNOWN"
		}
	}
}

I’ve put that all together into a script (couldn’t see that coming huh?): Get-LyncNumbers.ps1. Unless you have very few numbers, I definitely recommend piping the output of this script through Export-CSV and viewing the data in Excel, or maybe Out-GridView if you prefer that.

Side plug: if you are a .NET developer looking to do rate center lookups by NPA/NXX, be sure to check out my other project ThinkTel.LocalCallingGuide on GitHub and also in NuGet.

Keeping Lync Federated Domains Up To Date

Paul Vaillant — Fri, 13 Mar 2015 00:00:00 UTC

Federation is one of the best features of Lync. It let’s you connect with people outside your organization and get things done fast. Check out the Lync Directory for a sampling of organizations that are openly federated with Lync.

‘Open’ federation, what does that mean? When you try to connect to user@domain.com, and @domain.com is not a SIP Domain in your Lync environment, and you have enabled partner domain discovery (which is an Access Edge Configuration option), Lync will look up the DNS SRV record _sipfederationtls._tcp.domain.com and connect to the remote Lync environment.

There are a number of safe guards built in. There’s a great reference of Federation Safeguards for Lync on Technet. It says Lync 2010, but it gives you a sense of what’s going on. The key thing to note is that auto-discovered partners are subject to rate limiting. If there’s another Lync environment that you’re communicating heavily with, at some point you’re likely to run into these rate limits.

End user’s will see them manifest as presence not updating, or IM messages not being sent or received. In the Edge Server event log, you’ll see event ID 14603 indicating that a remote partner has been rate limited and event ID 14601 showing all autodiscovered partners.

How do you fix this? You use New-CsAllowedDomain to approve the domain for federation. Sure you could do it one domain at a time, but PowerShell to the rescue!

You can use PowerShell to parse out the event log entries and call New-CsAllowedDomain. It can be a little tricky since the event log entries are on the Edge Server and you can’t run New-CsAllowedDomain on the Edge Server. I wrote a script Update-LyncFederatedDomains.ps1 that gives you a few options.

Option 1: run on the Edge server and generate a script that you can run on the Front End. You can either use the -GUI option to get an interface that let’s you pick which domains to include in the script, or you can have the domains returned as PowerShell objects, filter them and use Update-LyncFederatedDomains to write them out to a script.

Update-LyncFederatedDomains.ps1 -GUI

Update-LyncFederatedDomains.ps1 | where Domain -match '.com$' | Update-LyncFederatedDomains.ps1 -FilePath .\path\to\front-end-script.ps1

Option 2: run it on a machine like the Front-End that can call New-CsAllowedDomain. You have the same option as above to either use a GUI or to use the command line, but you’ll probably need to specify credentials to connect to the Edge server using -Credential. The script will attempt to automatically detect the Edge server, but if you want to force it, use -EdgeServer. In the second example below, it will take all discovered domains and try to call New-CsAllowedDomain in the generated script.

Update-LyncFederatedDomains.ps1 -GUI -EdgeServer my-edge.acme.com -Credential $(Get-Credential)

Update-LyncFederatedDomains.ps1 -Credential $(Get-Credential) -FilePath .\path\tp\front-end-script.ps1

In the case where you use -GUI, you’ll need to click the Save button to generate the file. Then, whether you ran -GUI or used -FilePath, run the generated script and good bye rate limiting messages!

Happy keeping your federated domains approved!

Lync Utility Belt

Paul Vaillant — Fri, 06 Mar 2015 00:00:00 UTC

People want to come in to my office all day long. Which is fine, except when I’m on my wireless headset, listening to someone, which of course looks like I’m not on the phone, so they start talking. Before you ask, yes I’ve seen the Busylight, I have one in fact, but never really liked it. So I set out to make something different.

I was inspired by the idea of an on-air light that I could hang above my door so that my current status could be seen by people walking by. I had been wanting to get a Philips Hue light bulb and I figured this would be the perfect opportunity. I could even take it a step further then just on/off since the Philips Hue is an RGB LED bulb (it can show many different colors). It’s a neat system where you connect a base station to the network and then it becomes the API end point for controlling multiple individual light bulbs.

After getting my starter kit, I found a great library Q42.HueApi and start to code up my app. I didn’t want anything too heavy, so it’s a systray only application. It uses the Microsoft Lync 2013 SDK to connect to Lync and get notified of presence updates. That way, when you pick up the phone and your presence goes to ‘in a call’, the app sends a color change command to the Hue light bulb. It also

Once I had that going, I figured it would also be nice to connect it to Outlook so that my Lync presence would go ‘off work’ after the day is over, so I added that as well. And lastly, I often wonder where a phone number is from if I don’t recognize the number so I added a toast notification for incoming calls that shows what city the number is from. The data is via [Local Calling Guide](http://localcallingguide.com].

So why call it the Lync Utility Belt?

Well, where would Batman be without his…

Check it out on GitHub LyncUtilityBelt you can also download the binary below. You’ll need .NET 4.5+.

LyncUtilityBelt-1.0.0.zip

BTW: On-air light picture is from http://www.freeimages.com/photo/190552

Measuring Lync Conference Adoption

Paul Vaillant — Tue, 03 Mar 2015 00:00:00 UTC

I like data. There, I’ve said it and I’m not ashamed. The best decisions are made with good data. It helps take the decision making process from one of “I think” or “I hope” to “I know”.

I often use data to help customers better understand their environment and their users. When you have more than a small number of users, you can’t just walk around and ask the same question to everyone.

Recently I was working with a customer who had enabled all their users for every Lync feature quite some time ago. They were getting ready for an upgrade and wanted to re-gauge how the various Lync features were being used.

Gauging adoption is important for so many reasons. With this data you can ensure that users are actually using the feature you’ve enabled them for. If they aren’t, you can work with them to find out why and either correct it or adjust the expected model. This last is key because all of the sizing for a product as complex as Lync is based on a user models.

The first place I started with is how many people are hosting conferences and how many people are attending conferences. It’s important to gauge attendance as well as hosting because they have different implications. The great news is all the data you need is in the LcsCDR database!

Conference attendees can be retrieved using:


use LcsCDR;

with localUsers as (
	select distinct UserUri
	from Registration r join Users u on r.UserId = u.UserId
), confsAndUsers as (
    select 
        ConferenceStartTime, ConferenceEndTime, o.UserUri as orgUserUri, u.UserUri
    from Conferences c
        join Users o on c.OrganizerId = o.UserId
        join McuJoinsAndLeaves jl on jl.SessionIdTime = c.SessionIdTime and jl.SessionIdSeq = c.SessionIdSeq
        join Users u on jl.UserId = u.UserId
        join Mcus m on jl.McuId = m.McuId
        join UriTypes ut on m.McuTypeId = ut.UriTypeId
        left join FocusJoinsAndLeaves fjl on 
            fjl.SessionIdTime = c.SessionIdTime and fjl.SessionIdSeq = c.SessionIdSeq and fjl.UserId = jl.UserId
        left join ClientVersions cv on 
            fjl.ClientVerId = cv.VersionId
    where 
        (ut.UriType = 'conf:audio-video' or ut.UriType = 'conf:applicationsharing' or ut.UriType = 'conf:data-conf')
        and cv.ClientType != 256 and cv.ClientType != 16396
    group by ConferenceStartTime,ConferenceEndTime,o.UserUri,u.UserUri
)

select
    COUNT(*) as ParticipantCount, cu.UserUri
from
    confsAndUsers cu join localUsers lu on cu.UserUri = lu.UserUri
group by cu.UserUri

What I’m doing at the start here is getting a list of local users by getting the list of all users who have logged into this system. I do this because if an external user joins a meeting via federation, we have no means of knowing in the join/leave information and we only want to report on local users who have participated in meetings. Then I get a list of all the conferences and their organizers/participants. And lastly I select how many unique conferences each local user has participated in.

One value I sometimes also include is the cv.Version which is the User-Agent string that identifies what kind of client the user was using. This can be useful in knowing if users have a preference for what kind of client/device they connect to meetings with.

Similarly, conference organizers can be retrieved using:


use LcsCDR;

with confsAndUsers as (
    select 
        ConferenceStartTime, ConferenceEndTime, o.UserUri as orgUserUri, u.UserUri
    from Conferences c
        join Users o on c.OrganizerId = o.UserId
        join McuJoinsAndLeaves jl on jl.SessionIdTime = c.SessionIdTime and jl.SessionIdSeq = c.SessionIdSeq
        join Users u on jl.UserId = u.UserId
        join Mcus m on jl.McuId = m.McuId
        join UriTypes ut on m.McuTypeId = ut.UriTypeId
        left join FocusJoinsAndLeaves fjl on 
            fjl.SessionIdTime = c.SessionIdTime and fjl.SessionIdSeq = c.SessionIdSeq and fjl.UserId = jl.UserId
        left join ClientVersions cv on 
            fjl.ClientVerId = cv.VersionId
    where 
        (ut.UriType = 'conf:audio-video' or ut.UriType = 'conf:applicationsharing' or ut.UriType = 'conf:data-conf')
        and cv.ClientType != 256 and cv.ClientType != 16396
    group by ConferenceStartTime,ConferenceEndTime,o.UserUri,u.UserUri
),
confsAndAttendeeCounts as (
    select 
        ConferenceStartTime,
        CONVERT(varchar,(ConferenceEndTime - ConferenceStartTime),108) as Duration,
        orgUserUri as OrganizerUri,
        COUNT(*) as AttendeeCount
    from confsAndUsers
    group by ConferenceStartTime,ConferenceEndTime,orgUserUri having COUNT(*) > 1
)

select 
    COUNT(*) as HostingCount,
    MIN(AttendeeCount) as MinAttendeeCount,
    AVG(AttendeeCount) as AvgAttendeeCount,
    MAX(AttendeeCount) as MaxAttendeeCount,
    OrganizerUri as UserUri
from confsAndAttendeeCounts 
group by OrganizerUri

This returns all users who hosted conferences, along with how many conferences they hosted and the minimum, average and maximum number of participants. In this case we don’t need localUsers since only local users are able to host meetings in the first place. One note: when I say conferences I mean audio/video conference or application/desktop sharing (so not multi-party IM). This corresponds to the Lync Enterprise CAL.

Since both of these are dependant on the LcsCDR data, they are both subject to the standard warning that the time period you’re able to retrieve is set by the retention period of the cdr configuration (maybe I should have post just on that…). Once nice thing is these SQL scripts are compatible with both Lync 2010 and 2013.

Like many of my other SQL scripts, I also have a PowerShell script for this. In case you’re wondering, I like the PowerShell script version mainly so I never have to open the SQL Management Studio to run it. It’s also nice to be able to use PowerShell to dive into the data and slice is up on the fly. Plus you can easily export it to Excel with Export-CSV.

Get-LyncConferenceAdoption.ps1

ThinkTel in the NuGet

Paul Vaillant — Thu, 26 Feb 2015 00:00:00 UTC

Maybe a better title would have been “ThinkTel uControl libraries now available via NuGet” but I was going for more of a “ThinkTel in the house” feel. Because literary license¹. Before we get to the actual content, DISCLAIMER: I work for ThinkTel. That said, all views are my own.

Ok, with all that out of the way, if you are a ThinkTel customer this might be worth checking out. There are 2 libraries available via NuGet to help you manage your ThinkTel services:

Both are .NET interfaces to our uControl system. If you aren’t a ThinkTel customer, or don’t know what uControl is, here’s a quick synopsis. ThinkTel is a CLEC phone company in Canada (among other things) and uControl is our real-time service management portal that lets customers do things like create new SIP trunks, manage bindings, order DIDs and update v911 address information. If you you want to know more feel free to contact me or your account manager.

On to the interesting things. In addition to being a web portal, uControl is also a RESTful API so you don’t have to use our web interface, you can call the API from within your own systems. Our customers can do this for various reason; integrating phone number management with user provisioning/HR systems, automated service reconciliation, charge back accounting of usage to departments, wholesale level integration for rebranding purposes and many, many more scenarios.

There’s much more that our API can do then we have exposed in this library but it has all the basic things in it. If you are interested in something you can do in uControl but don’t see it in the API, or are curious about how you could use it for your own purposes but aren’t sure where to start, feel free to contact me.

Next up; using uControl via PowerShell!

English Has a New Preposition, Because Internet ↩

Last Login for a SIP URI

Paul Vaillant — Sun, 22 Feb 2015 00:00:00 UTC

Ever wanted to know when the last time someone logged in was? Ever wanted from where a user last logged in? Or even what client or client version someone is using? You could ask the user to provide this information but that would probably annoy them and give you information with a varying degree of accuracy. I always suggest you never ask users for something that you can figure out yourself and in this case all the information you need is in the LcsCDR database.

What is the LcsCDR database? It’s one of the two databases of the Monitoring role in Lync. It’s also in both Lync 2010 and Lync 2013, although the schema changed slightly between the two versions. The schema is available on TechNet if you’re really interested. The following query will retrieve the last 10 logins (aka registrations) for a given user SIP URI.


USE LcsCDR
SELECT TOP 10
    r.RegisterTime,
    r.DeRegisterTime,
    drt.DeRegisterReason,
    cv.Version as ClientVersion,
    r.IpAddress,
    r.ResponseCode,
    s.ServerFQDN as Registrar,
    p.PoolFQDN as Pool,
    e.EdgeServer,
    dbo.FormatMacAddr(d.MacAddress) as MacAddress,
    m.Manufacturer,
    hv.Version as HardwareVersion
FROM 
    Registration as r
    join Users as u on r.UserId = u.UserId
    join ClientVersions as cv on r.ClientVersionId = cv.VersionId
    join Servers as s on r.RegistrarId = s.ServerId
    join Pools as p on r.PoolId = p.PoolId
    left outer join EdgeServers as e on r.EdgeServerId = e.EdgeServerId
    left outer join DeRegisterType as drt on r.DeRegisterTypeId = drt.DeRegisterTypeId
    left outer join Devices as d on r.DeviceId = d.DeviceId
    left outer join Manufacturers as m on d.ManufacturerId = m.ManufacturerId
    left outer join HardwareVersions as hv on d.HardwareVersionId = hv.VersionId
WHERE 
    u.UserUri = 'john.doe@domain.com'
ORDER BY
    r.RegisterTime DESC

One quick note: if you were just interested in Lync 2013, this query could be made a little simplier by using the RegistrationView instead of the Registration table and joining a bunch of other tables. Unfortunately the RegistrationView in Lync 2010 is very different so by writing it out like this it’s portable* between the two (* Lync 2010 doesn’t have an IpAddress field in the Registration table so just remove that line).

Replace john.doe@domain.com and run this against the database for the pool the user is located in and you should get back the user’s last 10 logins. You can replace 10 with how ever many logins you want, or remove TOP 10 to get all their logins (up to the configured retention; see Get-CsCdrConfiguration).

A few notes: * you check TechNet for a list of possible DeRegisterReason * while ResponseCode will normally be 200 (OK), sometimes it can be something else. Check out the list of SIP response codes in those cases * MacAddress, Manufacturer and HardwareVersion will only have values if the user was logged in on a handset

In large environments with multiple pools, or in cases where users are moved around, you can use Get-CsService to get a list of monitoring databases and run this query against all of them. PowerShell can definitely make this task much easier:


$sql = @"
    ....
"@
$ds = New-Object System.Data.DataSet
Get-CsService -MonitoringDatabase | foreach {
    $dbSvr = if($_.SqlInstanceName) { 
        $_.PoolFQDN + "\" + $_.SqlInstanceName 
    } else { 
        $_.PoolFqdn 
    }
    $connStr = "Server=" + $dbSvr + ";Integrated Security=True"
    $conn = New-Object System.Data.SqlClient.SqlConnection $connStr
    $conn.open()
    $cmd = New-Object System.Data.SqlClient.SqlCommand $sql,$conn
    $da = New-Object System.Data.SqlClient.SqlDataAdapter $cmd
    [void]$da.fill($ds) 
    $conn.Close()
}
$ds.Tables[0] | sort RegisterTime -Descending | select -Last 10

You can actually download this SQL that uses a version of this PowerShell (with nice parameters and Lync 2010/2013 database detection) to run it against all Monitoring databases. Just drop it on a machine with the Lync PowerShell module and run it as a user that has access to the LcsCDR database (CSAdministrator member).

Get-LyncLogins.ps1 -UserUri john.doe@domain.com -Last 10

Want to get some data out of Lync but not sure how? Let me know and I’ll try to write some PowerShell and/or SQL for it.

Get-LyncLogins.ps1

Lync Backup Script

Paul Vaillant — Thu, 19 Feb 2015 00:00:00 UTC

Oh Lync, let me count the ways I love thee. Top of the list would be how I can manage everything with PowerShell. For an administrator, it’s not just about being able to do things without having to wait for a GUI, but it’s also about being able to create scripts and to automate or simplify the tasks that have to be done every day.

Who doesn’t like sitting back while a machine does all the hard work instead of feverishly clicking buttons and being frustrated at the responsiveness of the GUI?

PowerShell is also great for being able to get information, like the current configuration of the various parts of a Lync deployment. There are a few scripts out there already that leverage the Lync PowerShell cmdlets to create a snapshot of an environment but I was looking for something more. I wanted to be able to track how an environment changed. I wanted to be notified about those changes too so that I, and anyone else I was managing that environment with, would know when anyone else made a change. Big systems aren’t managed by one person after all.

In the Cisco/networking world this has been around for a long time. The typical example is RANCID. The way RANCID works is by storing configs in CVS or SVN (those are version control systems if you aren’t familiar with those acronyms). Why can’t we do something similar for Lync?

Enter Backup-Lync.ps1.

It runs as a scheduled task on any machine that has the Lync PowerShell module installed and access to the Lync environment. It uses the various get-cs* PowerShell cmdlets to get data, System.Linq.Xml to format the files nicely (basically to prettify the XML so that it’s on multiple lines rather than being all one big giant line) and GIT via libgit2sharp (a .NET interface to libgit2) as it’s version control system.

In addition to the configuration data, it can also keep track of user data (contacts, conferences, etc). It keeps these in one file per user and is extremely handy if someone deletes contacts by accident or if a user is disabled accidentally. It’s amazing how fast Disable-CsUser will purge out all the users data.

Give it a try and let me know what you think.

Backup-Lync.ps1

Hello, World!

Paul Vaillant — Mon, 16 Feb 2015 00:00:00 UTC

What better way to start a new blog then those famous first words. Well famous in computer science/IT/programming. If this doesn’t sound familiar to you I’ll give you a minute to check the following reference: “Hello, world!” on Wikipedia. Go ahead, I’ll wait.

Done?

Ok, now that we have that straight, I’ll say that I’m hoping to be able to put up new content about once a week. In a good week it might be twice.

That is all. Feel free to check out my twitter or github accounts for anything you might find interesting in a mean time.