PowerShell Scripting Lync 2010 SDK Using Lync Model API

Summary:   In this article you learn how to automate Microsoft Lync 2010 by using Microsoft Windows PowerShell scripting and Microsoft Lync Model API.

Applies to:   Microsoft Lync 2010 | Microsoft Lync 2010 SDK | Microsoft Windows PowerShell 2.0

Published:   March 2011 | Provided by:   Kurt De Ding, Microsoft | About the Author

Contents

• Introduction

• Obtain the Entry Point to the Lync Model API

• Inspect and Update Local User’s Phone Numbers

• Register for Change Notification of Contact Information

• Examine Local User’s Organization Information

• Publish Local User’s Presence Information

• Conclusion

• Additional Resources

Introduction

Microsoft Lync 2010 API includes the Microsoft Lync Model API and the Microsoft Lync Extensibility API. This article discusses Lync Model API PowerShell scripting. For information about Lync Extensibility API PowerShell scripting, see PowerShell Scripting Lync 2010 SDK Using Lync Extensibility API. This article describes how to complete the following tasks:

• Obtain the entry point to the Lync Model API and then sign in to Microsoft Lync Server 2010 if the user is not already signed in.

• Inspect and update local user’s phone numbers.

• Register for change notification of the local contact information.

• Examine the organization information for the local user, and discuss how to pass parameters by reference in a PowerShell script.

• Publish presence of the local user.

For information about how to download Microsoft Lync 2010 SDK and importing an assembly into a PowerShell session, see PowerShell Scripting Lync 2010 SDK Using Lync Extensibility API.

Obtain the Entry Point to the Lync Model API

To use the Lync Model API, you must first obtain the LyncClient object by calling the static GetClient method on the Microsoft.Lync.Model.LyncClient type. The following code example shows how to complete this task in PowerShell.

# Obtain the entry point to the Lync.Model API
$client = [Microsoft.Lync.Model.LyncClient]::GetClient()

Once you obtain the LyncClient object, you should verify that the Lync instance is signed in before you call other Lync Model API features. The following code example shows how to complete the task.

# Sign Lync in to Lync Server 2010, if Lync is not already signed in to the server.
if ($client.State -ne [Microsoft.Lync.Model.ClientState]::SignedIn)
{
    $client.EndSignIn(
        $client.BeginSignIn("user@contoso.com", "domain\user", "passwd", $null, $null))
}

Asynchronous calls are invoked in a synchronous manner throughout this article.

The code examples that appear next show how to program Lync Model API in PowerShell scripts.

Inspect and Update Local User’s Phone Numbers

The following code example shows how to inspect the available phone lines of the local user.

$self = $client.Self;

write-host ("Phone types:")
foreach ($pt in [Enum]::GetValues([Microsoft.Lync.Model.ContactEndpointType]))
{
    $ph = $null
    $ph = $self.GetPhone($pt) 
    " $pt : " + $ph.Endpoint.DisplayName + ", " + $ph.Endpoint.Uri | write-host
    trap [Exception]
    {
        # ignore unassigned phones 
        continue
    }
}

The following code example shows how to set the OtherPhone line of the local user.

#Set OtherPhone
$pt = [Microsoft.Lync.Model.ContactEndpointType]::OtherPhone
if ($self.CanSetPhone($pt))
{
    $ar = $self.BeginSetPhone($pt, "+1 (206)-555-0199", $true, $null, $null)
    $self.EndSetPhone($ar)
    "$pt added." 
}    

The following code example shows how to remove the OtherPhone line of the local user.

#Remove the OtherPhone
if ($self.CanSetPhone($pt))
{
    $ar = $self.BeginRemovePhone($pt, $null, $null)
    $self.EndRemovePhone($ar)
    "$pt removed."    
}

Register for Change Notification of Contact Information

The eventing process is widely used in Lync SDK and in other unified communications APIs that are supported in a Lync Server 2010 deployment. The following code example shows how to register and handle the ContactInformationChanged events in a PowerShell script. You can apply the technique to handle other events that are supported by this API and other unified communications APIs.

#Get a remote contact
$contact = $client.ContactManager.GetContactByUri("johnd@contoso.com");

#Register ContactInformationChanged events raised by the $contact object
Register-ObjectEvent -InputObject $contact `
  -EventName "ContactInformationChanged" `
  -SourceIdentifier "RemoteContactInformationChangedEvent" `
  -action { ContactInfoChangedEventHandler $sender $event }

#Event handler for ContactInformationChanged events
function ContactInfoChangedEventHandler ($sender, $event)
{ 
    $c = $sender -as [Microsoft.Lync.Model.Contact];
    $t = [DateTime]::Now;
    write-host "ContactInfomationChanged on $t for: " $c.Uri; 
    
    foreach($infoType in $event.SourceEventArgs.ChangedContactInformation) 
    {  
         write-host(" $infoType  = " + $c.GetContactInformation($infoType) );
    }
}

In the Register-ObjectEvent cmdlet, the InputObject parameter refers to the object ($contact) that raises the events of the specified event name (ContactInformationChanged). The SourceIdentifier parameter value is an application-specified string, which must be unique in a PowerShell session. The action parameter value refers to a script block that is invoked when the event is raised. In the previous code example, the action script block is expressed as a function (ContactInfoChangedEventHandler) with two input parameters. The parameters are used to pass some of the event’s automatic variables ($sender and $event) into the function.

The event registration must be canceled before your script ends or when you are no longer interested in the events. The following code example shows how to cancel the event registration that is discussed earlier.

#Cancel the ContactInformationChanged event registration
Unregister-Event "RemoteContactInformationChangedEvent"

The previous code example can be used to handle the ContactInformationChanged events that are raised by the local user’s Contact object, if the InputObject parameter value is changed to $self.Contact and the SourceIdentifier parameter value changed to a different unique string value, for example, LocalContactInformationChangedEvent.

Examine Local User’s Organization Information

The following code example shows how to retrieve the organization information from the local user’s Contact object. It can also be applied to a remote contact.

# Retrieve the local user's organization information
# Specify types of the organization information by setting the OrganizationStructureTypes bit flags
$orgStruct = [Microsoft.Lync.Model.OrganizationStructureTypes]::Managers 
$orgStruct = $orgStruct -bor [Microsoft.Lync.Model.OrganizationStructureTypes]::Peers
$orgStruct = $orgStruct -bor [Microsoft.Lync.Model.OrganizationStructureTypes]::Directs

# Initialize the $managers, $peers and $directs objects. 
# Initialization is required to pass the objects by 
# reference into the EndGetOrganizationInformation method.
$managers = $null
$peers = $null
$directs = $null

$ar = $self.Contact.BeginGetOrganizationInformation($orgStruct, $null, $null)
$self.Contact.EndGetOrganizationInformation([ref] $managers, [ref] $peers, [ref] $directs, $ar)

write-host "managers: "
if ($managers)
{
  foreach($c in $managers)
  {
    $m = $c -as [Microsoft.Lync.Model.Contact]
    $m.Uri | write-host
  }
}

write-host "peers:"
if ($peers)
{
   foreach($c in $peers)
   {
     $p = $c -as [Microsoft.Lync.Model.Contact]
     $p.Uri | write-host
   }
}

write-host "directs:"
if ($directs)
{
  foreach($c in $directs)
  {
    $d = $c -as [Microsoft.Lync.Model.Contact]
    $d.Uri | write-host
  }
}

In the previous code example, $orgStruct corresponds to bit-wise flags that is used to filter the kind of organization information that is retrieved. Here, the code is designed to find the managers, peers and direct reports that are associated with the local user. This is specified by combining the three options using bitwise OR operators (-bor).

The Lync Model API documentation shows that the C# syntax of the EndGetOrganizationInformation method has three out parameters that return the retrieved managers, peers, and directs reports. In PowerShell, this kind of out parameter is qualified with [ref] keywords that must be initialized with $null values before they are passed to the method call.

Publish Local User’s Presence Information

The following code example shows how to publish presence information for a local user.

#Publish personal note and presence availability of the local user
$date = [DateTime]::Now
$availability = 6500
$contactInfo = new-object 'System.Collections.Generic.Dictionary[Microsoft.Lync.Model.PublishableContactInformationType, object]'
$contactInfo.Add([Microsoft.Lync.Model.PublishableContactInformationType]::PersonalNote, 
                "Set availability to $availability using the Lync Model API in PowerShell on $date")
$contactInfo.Add([Microsoft.Lync.Model.PublishableContactInformationType]::Availability, 
                $availability)

$ar = $self.BeginPublishContactInformation($contactInfo, $null, $null)
$self.EndPublishContactInformation($ar)

In the previous code example, the presence publication includes only the personal note and presence state availability number. The availability number ($availability) is set to an integer value of 6500, which indicates that the local user is busy. The personal note is only a string. If you have registered for the ContactInformationChanged events on the local user’s Contact object, the publication forces this kind event to run and the new data should be caught by the registered event handler.

You can also set the presence availability value by using the ContactAvailability enumeration. The following code example shows how to use ContactAvailability to set the value.

$availability = [Microsoft.Lync.Controls.ContactAvailability]::Busy

As shown in the following example, at the beginning of the code file, ensure that you add a reference to the Microsoft.Lync.Controlls.dll assembly.

import-module "C:\Program Files (x86)\Microsoft Lync\SDK\Assemblies\Desktop\Microsoft.Lync.Controls.Dll"

Conclusion

In this article, various PowerShell scripts are used to call into Lync Model API. This article discussed how to use PowerShell scripting and the Lync Model API to complete the following tasks:

• Sign in to Lync Server 2010.

• Inspect and update local user information.

• Register event handlers to receive event alerts.

• Obtain organization information that is associated with a user and pass parameters by reference in a PowerShell script.

• Publish a local user’s presence information.

Additional Resources

For more information, see the following resources:

• Windows PowerShell

• Windows PowerShell v2.0 Reference

• PowerShell Scripting Lync 2010 SDK Using Lync Extensibility API

• Microsoft Lync 2010 SDK

• Unified Communications Managed API 3.0 Core SDK Documentation

• Microsoft Lync 2010 SDK documentation

About the Author

Kurt De Ding is a Senior Programming Writer, Microsoft Office Content Publishing (UA) group.