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 athttp://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-ObjectSystem.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-ObjectSystem.Management.ManagementClass("MSFT_SIPESUserContactGroupData")).CreateInstance()
$ContactGroup.UserInstanceID = $User.InstanceID
$ContactGroup.Name = "NAME OF GROUP HERE"
$ContactGroup.ExternalURL = "<groupExtension groupType=`"dg`"><email>group@domain.com</email></groupExtension>"

#Create and commit group
$ContactGroup.PsBase.Put($PutOptions)

Checking if a Contact Distribution 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 {$_.ExternalURL -like"*group@domain.com*"})

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 Distribution 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 {$_.ExternalURL -like"*group@domain.com*"})

#Delete the group
$ContactGroup.Delete()

Individual Contact Management

The MSFT_SIPESUserContactData WMI class exposes the ability to view and modify contacts for OCS users.  Using this class you can add/delete contacts allowing you to define contact group memberships as necessary. This WMI class is documented at http://msdn.microsoft.com/en-us/library/dd185919(office.13).aspx.

Below are PowerShell scripting examples demonstrating specific tasks related to user contact list 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

#Get User Information
$User = Get-WmiObject -Query "Select * from MSFT_SIPESUserSetting where PrimaryURI = 'sip:user@domain.com'"
$UserInstanceID = $User.InstanceID 

#Create Contact instance
$Contact = (New-ObjectSystem.Management.ManagementClass("MSFT_SIPESUserContactData")).CreateInstance()
$Contact.UserInstanceID = $User.InstanceID
$Contact.SIPURI = "sip:userToBeAdded@domain.com"
$Contact.Subscribed = $True

#These next steps are optional unless you want to assign a contact to a contact group
$ContactGroup = (Get-WmiObject -Query "Select * from MSFT_SIPESUserContactGroupData where UserInstanceID ='$UserInstanceID'" | Where {$_.Name -like "NAME OF GROUP HERE"})
$Contact.GroupID = $ContactGroup.GroupID

#Create and commit contact
$Contact.Put()

Checking if a Contact Exists

#Get User Information
$User = Get-WmiObject -Query "Select * from MSFT_SIPESUserSetting where PrimaryURI = 'sip:user@domain.com'"
$UserInstanceID = $User.InstanceID

#Check if contact is already added to user's contact list
$Contact = (Get-WmiObject -Query "Select * from MSFT_SIPESUserContactData where UserInstanceID = '$UserInstanceID'" |Where {$_.SIPURI -like "sip:userToCheck@domain.com"})

if ($Contact -ne $null) { #The contact is on the user's contact list
      Write-Host "The contact exists on the user's contact list"
}
elseif ($Contact -eq $null) { #The contact is not on the user's contact list
      Write-Host "The contact does not exist on the user's contact list"
}

Removing a Contact

#Get User Information
$User = Get-WmiObject -Query "Select * from MSFT_SIPESUserSetting where PrimaryURI = 'sip:user@domain.com'"

#Get the contact on the user's contact list
$Contact = (Get-WmiObject -Query "Select * from MSFT_SIPESUserContactData where UserInstanceID = '$UserInstanceID'" |Where {$_.SIPURI -like "sip:userToDelete@domain.com"})

#Delete the contact
$Contact.Delete()

Original Author Nick Smith/ Microsoft