Automating Microsoft Lync using Windows PowerShell

Microsoft Lync is the client for Microsoft`s unified communications platform Lync Server. The Lync client API includes the Microsoft Lync Model API and the Microsoft Lync Extensibility API, which is primarily targeted at developers who are building custom Lync applications or integrations with Line-Of-Business applications. The API is available in the Lync SDK (Software Developer Kit), the SDK for the latest version for the Lync client is available here. Since the SDK is .NET it is possible to leverage Windows PowerShell to access it. When the SDK is installed, you simply import the assembly Microsoft.Lync.Model.dll as a binary module using Import-Module:

Import-Module –Name “C:\Program Files (x86)\Microsoft Office\Office15\LyncSDK\Assemblies\Desktop\Microsoft.Lync.Model.dll”

In the Lync 2010 SDK documentation there is a great introduction to working with the Lync SDK from PowerShell, this also applies to the Lync 2013 SDK. See the article PowerShell Scripting Lync 2010 SDK Using Lync Model API.

In order to have a practical task to solve, I decided to try to configure the availability for the Lync client. Typically I want to configure my availability to “Available” when I get to work in the morning, and “Off Work” when I leave at the end of the day (my work computer is always powered on). I often forget to change the status, so I decided to use the new Scheduled Jobs functionality introduced in Windows PowerShell 3.0 in order to schedule the configuration of my Lync availability.

I have created a PowerShell function, Publish-LyncContactInformation, which makes it possible to configure Lync availability, location and personal note:

For the Availability parameter, the ValidateSet parameter validation attribute is used to validate the supplied parameters. This also gives us Intellisense in the PowerShell ISE:

image

Availability is provided with integer values, the possible values is available here. To make it more user friendly a switch statement is used to map the string values to the correct integer value, this makes it possible for the user to supply “Available” instead of “3000” as the parameter value.

What I could not find a value for was the “Off Work” status. It turns out that the Activity Id also must be configured in order to set availability to “Off Work” (thanks to Jens Trier Rasmussen for helping me with this one), more info here. Example usage: Publish-LyncContactInformation -Availability “Off Work” -ActivityId off-work

There are a number of presence items which can be configured, you can find more info here. In addition to the Availability and Activity Id I also included Personal Note and Location as parameters. It is also possible to add more items if needed, for example Photo URL.

Several examples on how to use the function is included in the help, run Get-Help Publish-LyncContactInformation –Examples to view them:

image

In example 5, a function is used to set the personal note in Lync. You can find the function here. After running the command in example 5, my Lync client presence looked like this:

image

Using Register-ScheduledJob, I have configured the function to run at 8.00 in the morning and 16.00 in the afternoon:

image

You can find an example on how to schedule the Publish-LyncContactInformation function here.

There are a couple of gotchas I would like to mention at the end:

#1: When using Register-ScheduledJob, the task created in \Microsoft\Windows\PowerShell\ScheduledJobs in the Task Scheduler is configured with the option “Run whether the user is logged on or not”. In order for [Microsoft.Lync.Model.LyncClient]::GetClient() to work properly from the scheduled job, the option must be set to “Run only when user is logged on”:

image

I have not found any way to configure this option using the cmdlets in the PSScheduledJobs module, so I configured this manually from the Task Scheduler. I will update this article when I have more information.

Update 2013-08-09: Using the Set-ScheduledTask cmdlet from the ScheduledTasks module works fine:

$principal = New-ScheduledTaskPrincipal -LogonType Interactive -UserId “$($env:USERDOMAIN)\$($env:USERNAME)”
Set-ScheduledTask -TaskName “\Microsoft\Windows\PowerShell\ScheduledJobs\Publish-LyncContactInformation – Off Work” -Principal $principal
Set-ScheduledTask -TaskName “\Microsoft\Windows\PowerShell\ScheduledJobs\Publish-LyncContactInformation – Available” -Principal $principal

The above will configure the “Run only when user is logged on” option for the two scheduled jobs in the examples.

about_Scheduled_Jobs states the following regarding scheduled jobs and scheduled tasks:

NOTE: You can view and manage Windows PowerShell scheduled jobs     in Task Scheduler, but the Windows PowerShell job and Scheduled     Job cmdlets work only on scheduled jobs that are created in     Windows PowerShell.

Based on this, my understanding is that modifying a scheduled task created by Register-ScheduledJob using Set-ScheduledTask is supported.

#2: When running the Lync SDK setup file I encountered the following error:

image

In order to avoid having to install Visual Studio, extract the exe-file using for example 7-Zip. Then you can install the Lync SDK by running the MSI-file from the extracted folder.

Browsing PowerShell Commands using a grid window

Get-CommandGridView is a PowerShell function written by PowerShell MVP Jeffery Hicks, which he blogged about here. I think this is a nice way to explore what is available in PowerShell modules and snapins. The function will show the available cmdlets in the specified module or snapin in a grid window, showing the properties Name,Noun,Verb,CommandType and ModuleName:

image

I think this is a great way to explore new modules/snapins, but I also thought it would be a good idea to leverage the new –PassThru switch on Out-GridView introduced in PowerShell 3.0 to let the user select commands to be sent to Get-Help –ShowWindow to further explore the help for interesting cmdlets/functions. I modified Jeff`s original function to provide this functionality:

Here is an example from running Get-CommandGridView -Module Hyper-V:

image

You can now select one or more cmdlets (using Shift or Ctrl + select) and then hit the OK button to bring up help windows for the selected cmdlets:

image

image

If no module is specified, all cmdlets and functions will be retrieved. That could potentially be thousands of cmdlets/functions, so in order to protect the user from opening to many help windows I added a validation attributte to the MaxHelpWindowCount parameter.

The functionality of the Get-CommandGridView function is similar to the Show Command Add-on introduced in PowerShell ISE 3.0, but I think it is more convenient when exploring new modules.

Here is a screenshot of the Show Command Add-on for those who have not seen it:

image