Administratively Managing User Contact Lists

Administratively Managing User Contact Lists

  • Comments 5
  • Likes

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"

$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-Object System.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()

 

 

Comments
  • I had problems to run the ps1 to Adding a Contact in Individual Contact Management.

    I have got the following errors:

    Get-WmiObject :

    At C:\Users\administrator\desktop\2s.ps1:13 char:31

    + $ContactGroup = (Get-WmiObject <<<<  -Query "Select * from MSFT_SIPESUserCont

    actGroupData where UserInstanceID = '$UserInstanceID'" | Where {$_.Name -like "

    2s_todos"})

       + CategoryInfo          : InvalidOperation: (:) [Get-WmiObject], COMExcept

      ion

       + FullyQualifiedErrorId : GetWMICOMException,Microsoft.PowerShell.Commands

      .GetWmiObjectCommand

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

    At C:\Users\administrator\\desktop\2s.ps1:17 char:13

    + $Contact.Put <<<< ()

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

       + FullyQualifiedErrorId : DotNetMethodException

  • I have a similar problem with the Put Method. Does anybody have an Idea ?

    PS c:\>$ContactGroup.Put($PutOptions)

    Exception calling "Put" with "1" argument(s): ""

    At line:1 char:18

    + $ContactGroup.Put <<<< ($PutOptions)

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

       + FullyQualifiedErrorId : DotNetMethodException

  • These errors indicate that an error was returned by WMI when trying to save the obect - maybe some parameter was invalid, you don't have permission, or any number of other issues.

    You can see more info by doing

    $e =$error[0]

    Then looking at the properties of the exception that was thrown:

    $e.Exception

    $e.Exception.StackTrace

    etc

    That may give a clearer indication of what went wrong.

  • You can save time and effort on this issue. I have been struggling with adding groups and contacts first for OCS, and now for Lync till i found a great software that solved that problem. It is called Contacts Manager, and i recommend it for every OCS/Lync adminstrator.

    http://www.ocscm.com

  • Scripts are free!  Contacts Manager is not.

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment