Provisioning OCS From the Command Line

At the heart of OCS administration is enabling or disabling a particular user for OCS 2007 and setting various OCS features (a.k.a. provisioning a user).  This can be done through the OCS Management Console, but many administrators ask how to do it through the command line so that this functionality can be integrated with existing provisioning processes.

In a nutshell there are 4 options:

  1. Use a Windows Script (e.g. VBScript or JavaScript/JScript)
  2. Use the OCS 2007 Resource Kit Script (LCSEnableConfigureUsers.wsf)
  3. Use Microsoft Powershell
  4. Use a Bulk Active Directory Import/Export Tool

I explore these 4 options below. The first 3 options make use of WMI under the covers to set the “Enabled” property on the OCS user in Active Directory.

Note: this post focuses on OCS user provisioning through the command line. OCS also has broader administrative capabilities through the command line.  The OCS R2 Command Line Reference Document and the OCS 2007 Command Line Reference Document covers more scope and details.

Important notes for the first 3 (WMI-based) Options:

  1. All options require the OCS WMI class MSFT_SIPESUserSetting to be available locally. The OCS Administrative Tools installs this WMI class and is an important pre-requisite.
  2. Any of these solutions require the appropriate permissions to access the Active Directory user objects. The user you run as should be a member of the RTCUniversalUserAdmins group.
  3. These options assume that the underlying AD user object has been created.  The VBScript example also assumes that the user has been OCS enabled – that is, the underlying AD object has been enabled at least once for OCS. See the blog entry AD Properties Required to Enable a User for OCS for what happens the first time an AD object has been enabled for OCS.
  4. The WMI attribute the “EnabledForEnhancedPresence” property controls whether the user is enabled for Enhanced Presence and can sign-in with the new Communicator 2007 client (for the corresponding AD attribute, see the related blog post “Provisioning OCS Users (and the AD msRTCSIP-OptionFlags Attribute“).

Option 1: Using a Script (e.g. VBScript or JavaScript/JScript)

I’ve put together a sample VBScript to enable or disable a single OCS user.  Set the g_userURI and g_OCSEnableUser variables accordingly. You can use the guts of this script to easily do it for a batch of users (i.e. read a list of users from a file).

WScript.Echo “Starting”

‘ SET THE USER WE WANT TO ENABLE or DISABLE
g_userURI = “sip:someTestUser@SIPDomain.com”

‘ TRUE TO ENABLE or FALSE TO DISABLE
g_OCSEnableUser = True

‘ Connect to a WMI object
Set wmiServer = CreateObject(”WbemScripting.SWbemLocator”).ConnectServer()

‘ Get the SIP User
Query = “SELECT * FROM MSFT_SIPESUserSetting where PrimaryURI = ‘” & g_userURI & “‘”

Set OCSUsers = wmiServer.ExecQuery(Query)

If ( IsEmpty(OCSUsers) Or OCSUsers.Count = 0) Then
WScript.Echo “No matching SIP user was found.”
Else
For each OCSUser in OCSUsers
PrimaryURI = OCSUser.PrimaryURI
HomeServerDN = OCSUser.HomeServerDN
UserDN = OCSUser.UserDN

‘ Wscript.Echo “URI: ” & PrimaryURI & Chr(13) & Chr(10) & HomeServerDN & Chr(13) & Chr(10) & UserDN

OCSUser.Enabled = g_OCSEnableUser

Err.Clear()

OCSUser.Put_ 0     ‘ 0 for create or update

If Err = 0 Then
WScript.Echo “Operation Successfull”
Else
WScript.Echo “Detected an error”
End If
Next
End If

Option 2: Using an OCS 2007 Resource Kit Script

The kit includes a windows script file called LCSEnableConfigureUsers.wsf, which contains VBScript that uses WMI to batch enable or disable users for OCS.

The script requires 2 input files: one file containing a list of users to enable or disable (specified with their SIP or distinguished names), and another file with the corresponding OCS user settings.

These files require some time and effort to set up, so this option is best for big batch operations. The Resource Kit ReadMe contains good information on prerequisities and permissions expected for this script.

Option 3: Using Microsoft PowerShell

Microsoft PowerShell is a powershell scripting environment that comes with a WMI provider that can be used to manage OCS. Powershell can be downloaded here.  Starting in Windows 2008, Powershell was included with part of the operating system. You can download Powershell 1.0 here: http://www.microsoft.com/windowsserver2003/technologies/management/powershell/download.mspx if you have Windows 2003. Once installed, you can easily script a solution to enable/disable OCS users.

Option 3a – The underlying AD user object has been enabled for OCS (or LCS) at least once.

If the AD user has never been enabled for OCS (or LCS), you will not be able to use this method to enable the user (they won’t show up in the MSFT_SIPESUSERSETTING class).  See Option 2 (below) .

To get a list of OCS Enabled users, you can simply issue the command:
> get-wmiobject -class msft_sipesusersetting | ForEach-Object { $_.Enabled = true}

To enable a particular SIP user for OCS:
>   get-wmiobject -class MSFT_SIPESUserSetting | where-object { $_.PrimaryURI -eq “sip:userid@SIPDomain” } | % { $_.Enabled = $True; $_.put() | out-null }

Note: the “%” is a Powershell shorthand alias for ForEach-Object.
Option 3b – The underlying AD user object has never been enabled for OCS (or LCS).
Rather then take up a lot of space in this blog entry showing the Powershell script to do it, I’ve made it available here: EnableOCSUser.ps1.
The heart of this script enables a user by:
1.  Creating a new instance of the WMI MSFT_SIPESUserSetting class.
2. Setting the attributes Enabled, PrimaryURI, UserDN, HomeServerDN, and EnabledForEnhancedPresence.
This function requires 3 input parameters, 2 of which are distinguished names from AD. I’ve posted another script called ADSearch.ps1 which will help you programmatically query for these attributes.
If you get an exception which looks like this “Exception calling “Put” with “0″ argument(s): “Exception calling “Put” with “0″ argument(s):“ on the WMI.Put() call to create the OCS user, usually it is:
  • One or more of your parameters is not correct, or,
  • The OCS WMI object already exists for that user
There is also a nifty GUI available to help create, manage and run Powershell scripts: PowerGUI (www.powerGUI.org). I created an OCS Powerpack last has this functionality and a whole lot more: http://www.powergui.org/entry!default.jspa?categoryID=21&externalID=1926&fromSearchPage=true.

Option 4: Use a Bulk Active Directory Import/Export Tool

Many OCS user features that can be set in the OCS management console GUI can be set or changed through underlying Active Directory (AD) attributes.  If you are attempting a bulk change, you’ll generally want to export the users, modify the data (to turn a feature on or off), and re-import the data.  The following two command line tools will allow you to do this:

  1. LDIFDE – Export / Import data from Active Directory.  LDIFDE  Import/export information from/to Active Directory. It queries any available domain controller to retrieve/update AD information.
  2. CSVDE (Comma Separated Value Data Exchange).  CSVDE is a small command-line tool that can import and export data from AD in a CSV file. It is included in Windows 2003 installs by default (usually in the %windir%/system32 directory).

Although not a command-line tool per se, ADModify.NET is an excellent GUI based tool for making batch changes to objects in AD.  It can record all changes that it made to an XML file which is handy.

Share and Enjoy:
  • Twitter
  • Digg
  • StumbleUpon
  • del.icio.us
  • Facebook
  • LinkedIn
  • MySpace
  • Reddit
  • Technorati

8 comments to Provisioning OCS From the Command Line

  • Yps

    I got ‘Get-WmiObject : Invalid class’ when I run it from Exchange Shell ? Anyone got a clue what´s wrong?

  • david

    Hi Curtis,

    I am a bit confused to what is generally referred to as ENABLING and PROVISIONING. Can a user be configured to use OCS by ONLY setting their AD attributes directly? Or do their AD attributes need to bet set, AND the WMI provider be used to provision them?

    To understand this better I’m trying to see the link between the WMI MSFT_SIPESUserSetting class properties, and the AD attributes of the user. The only relation I see is that some of the MSFT_SIPESUserSetting class properties are synced to the msRTCSIP-OptionFlags AD Attribute.

    My goal is basically to enable/provision OCS for users through C# code – which is done pretty easily by simple settings a few AD attributes. But the confusion is whether this is possible without using a WMI provider.

    Thanks so much for your help, the your posts have been really useful.

    David

  • Hi Saravanan,

    The associated user AD object needs to be enabled for OCS before you can programmatically provision the user for OCS using the WMI provider (and WMI classes like MSFT_SIPESUSERSETTING). You can enable an AD user object for OCS by setting values for three AD attributes/properties: msRTCSIP-UserEnabled, msRTCSIP-PrimaryUserAddress, and msRTCSIP-PrimaryHomeServer. For the user to be able to logon with Communicator 2007 R2 with Enhanced Presence, you will also need to set msRTCSIP-OptionFlags to a value of 256 (or higher).

    Many OCS user features can be provisioned in AD, these 3 properties are just the minimum to enable the OCS users.

    To set those AD attributes, you have several choices: scripting (e.g. VBScript) if you want to write an automated process, or several of the AD tools that I highlight in Option #4 if you want to do a batch enable.

    I will follow-up with a blog posting concerning this (several people are in this scenario).

    Hope that helps,
    Curtis

  • Saravanan

    Hi,

    Thanks for the post.

    You have mentioned MSFT_SIPESUSERSETTING does not retrieve objects which were never been provisioned to OCS or LCS. Thats exactly the situation for me, where I need to retrieve user objects who are created new in the system (through some other automation) and enable them for using OCS. Since this WMI class does not return any users, am not able to provision OCS for them either.

    Is there any prior step I need to perform?

    Thanks,
    Saravanan

  • [...] – Provisioning OCS From the Command Line – Enable existing user for Communications Server – Provisioning OCS Users (and the AD [...]

  • [...] Properties Required to Enable a User for OCS As a follow-on to my popular post “Provisioning OCS From the Command Line”, several readers noted that they were in the situation where the OCS user had not been created [...]

  • [...] Because this is a bit-mask, becareful not to clobber any existing features. For example, if you are setting Enhanced Presence (bit 256), and want to preserve the ability for the user to have Public IM functionality, be sure to set the value to 257 (i.e. add a “1″ to set the enabled for PIC bit). A good way to approach this is to add the value of the bit representing the feature you want to add to the existing value. You can do this through several command line options outlined in my blog post “Provisioning OCS From the Command Line“). [...]

Leave a Reply

 

 

 

You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>