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 "