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:
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:
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:
Using Register-ScheduledJob, I have configured the function to run at 8.00 in the morning and 16.00 in the afternoon:
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”:
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:
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.