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:

Use a Windows Script (e.g. VBScript or JavaScript/JScript)

Use the OCS 2007 Resource Kit Script (LCSEnableConfigureUsers.wsf)

Use Microsoft Powershell

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.

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.

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.

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.

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).

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.

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:

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:

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.

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.

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).

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.

[...] 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“). [...]

OCS Search

Loading

Legal

The posts and information on this blog are provided "as is" with no warranties and confer no rights. The opinions expressed on this site are mine and mine alone, and do not necessarily represent those of my employer or anyone else for that matter. All trademarks acknowledged. Copyright 2009 Curtis Johnstone.