Administratively Managing User Contact Lists


WMI Namespaces and Scripting Examples

 

By Nick Smith, Microsoft

 

Introduction

 

Your company has a requirement to administratively add/remove/modify the membership of Microsoft Office Communications Server 2007 R2 users’ contact lists.  This document provides Windows PowerShell scripting examples for managing OCS users’ contact lists via the supported Windows Management Instrumentation (WMI) namespaces.  The PowerShell scripting examples will cover managing contact groups, distribution groups, and individual contacts.

 

Purpose

 

The LCSAddContacts.wsf script included in the Office Communications Server 2007 R2 Resource Kit Tools provides a full end-to-end script for adding and deleting contacts from user contact lists.  However, the LCSAddContacts.wsf script does not provide the ability to accomplish specific tasks such as deleting a contact group or adding a distribution list to a contact list. This document will detail granular tasks and the WMI namespaces that can be used to manage user contact lists for both individual contacts and groups. PowerShell script examples will be provided to demonstrate how to accomplish each task.

 

Audience

 

This document is intended for Office Communications Server administrators that require the ability to administratively add/remove/modify contacts from individual user contact lists.

 

Disclaimer

 

The WMI classes used in the scripting examples are supported by Microsoft.  The WMI classes are the only supported methodfor administrative contact list management available in OCS 2007 R2.

 

The sample code contained in this document is intended for demonstration purposes only.  The scripts are intended to demonstrate functionality; no error checking has been added.  All code is provided as-is and if you choose to implement or enhance the scripts you will be responsible for any subsequent maintenance and support.

 

Contact Group Management

 

The scripts in this section demonstrate how to manage contact groups in OCS 2007 R2 by using WMI and Windows PowerShell.

 

Contact Groups

 

The MSFT_SIPESUserContactGroupData WMI class exposes the ability to view and modify contact groups for OCS users.  Using this class you can add/delete contact groups, allowing you to define the group name. This WMI class is documented at http://msdn.microsoft.com/en-us/library/dd146647(office.13).aspx.

 

Below are PowerShell scripting examples demonstrating specific tasks related to user contact list group management.  Each sample script can be run independently.  The highlighted values in the scripts should be changed to the intended values for proper outcomes.

 

Adding a Contact Group

 

#Define WMI Put options

$PutOptions = New-Object System.Management.PutOptions

$PutOptions.Type = 2 #CreateOnly

 

#Get User Information

$User = Get-WmiObject -Query “Select * from MSFT_SIPESUserSetting where PrimaryURI = ‘sip:user@domain.com‘”

 

#Create ContactGroup instance

$ContactGroup = (New-Object System.Management.ManagementClass(“MSFT_SIPESUserContactGroupData”)).CreateInstance()

$ContactGroup.UserInstanceID = $User.InstanceID

$ContactGroup.Name = NAME OF GROUP HERE

 

#Create and commit group

$ContactGroup.PsBase.Put($PutOptions)

 

Check if a Contact Group Exists

 

#Get User Information

$User = Get-WmiObject -Query “Select * from MSFT_SIPESUserSetting where PrimaryURI = ‘sip:user@domain.com‘”

$UserInstanceID = $User.InstanceID

 

#Check if group is already added to user’s contact list

$ContactGroup = (Get-WmiObject -Query “Select * from MSFT_SIPESUserContactGroupData where UserInstanceID = ‘$UserInstanceID'” | Where {$_.Name -like NAME OF GROUP HERE})

 

if ($ContactGroup -ne $null) { #The group is on the user’s contact list

      Write-Host “The group exists on the user’s contact list”

}

elseif ($ContactGroup -eq $null) { #The group is not on the user’s contact list

      Write-Host “The group does not exist on the user’s contact list”

 

Removing a Contact Group

 

#Get User Information

$User = Get-WmiObject -Query “Select * from MSFT_SIPESUserSetting where PrimaryURI = ‘sip:user@domain.com‘”

 

#Get the contact group on the user’s contact list

$ContactGroup = (Get-WmiObject -Query “Select * from MSFT_SIPESUserContactGroupData where UserInstanceID = ‘$UserInstanceID'” | Where {$_.Name -like NAME OF GROUP HERE})

 

#Delete the group

$ContactGroup.Delete()

 

 

Contact Distribution Groups

 

Office Communicator 2007 and Office Communicator 2007 R2 provide the ability to add any mail-enabled group in Active Directory to a user’s contact list. The group and all the OCS-enabled members will be displayed on the user’s contact list.

 

The MSFT_SIPESUserContactGroupData WMI class exposes the ability to view and modify contact groups for OCS users.  Using this class you can add/delete contact groups, allowing you to define the group name and ExternalURL.  A distribution group is specified by XML content stored in the ExternalURL property. This WMI class is documented at http://msdn.microsoft.com/en-us/library/dd146647(office.13).aspx.

 

Below are PowerShell scripting examples demonstrating specific tasks related to user contact list distribution group management.  Each sample script can be run independently.  The highlighted values in the scripts should be changed to the intended values for proper outcomes.

 

Adding a Contact Distribution Group

 

#Define WMI Put options

$PutOptions = New-Object System.Management.PutOptions

$PutOptions.Type = 2 #CreateOnly

 

#Get User Information

$User = Get-WmiObject -Query “Select * from MSFT_SIPESUserSetting where PrimaryURI = ‘sip:user@domain.com‘”

 

#Create ContactGroup instance

$ContactGroup = (New-Object System.Management.ManagementClass(“MSFT_SIPESUserContactGroupData”)).CreateInstance()

$ContactGroup.UserInstanceID = $User.InstanceID

$ContactGroup.Name = NAME OF GROUP HERE

Comments (10)
  1. Adam Johnson says:

    But scripts have proven they are not as effective as managing contacts centrally using Contact Manager or OCSCM..

    There's a huge difference, you may wanna give it a shot for a free trial

    http://store.egyptnetwork.com/

  2. Salva says:

    Hi all,

    I'm trying the Removing a Contact Group script and I get this :

    Exception calling "Delete" with "0" argument(s): ""

    At C:UsersadminDesktopUntitled2.ps1:11 char:21

    + $ContactGroup.Delete <<<< ()

       + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException

       + FullyQualifiedErrorId : DotNetMethodException

    Can anyone help me?

    I also tried $ContactGroup.psBase.Delete(), but no success reply…

    Thanks

  3. While scripts are free, they lack a lot of features and capabilities that Contact Manager can address. Contact Manager for Lync has the ability to administer contact lists in a more central and automatic way and keeps the corporate contact list organized and unified. It does the job of what every Lync admin is really looking for. It is a great product!

    http://www.vytru.com/contacts-manager.html

  4. David says:

    is there an equivalent tool for Lync 2010

  5. David says:

    is there an equivalent tool for Lync 2010

Comments are closed.

Skip to main content