Ten Steps to PowerShell Scripting with Office Communications Server 2007 R2

Set the PowerShell Execution Policy

You’ll need to set the PowerShell Execution Policy levels. They are as follows:

• Restricted

• Unrestricted

• AllSigned

• RemoteSigned

The default Execution Policy level is set to Restricted for a new installation of PowerShell. The Restricted Execution Policy allows neither PowerShell commands to be accessed nor PowerShell configuration files to be loaded. So to continue with our demonstration, we will have to set the PowerShell Execution Policy to a more liberal level.

Paste the following from your PowerShell command prompt (taking the action shown):

Get-ExecutionPolicy

(List your current ExecutionPolicy)

Get-Help ExecutionPolicy

(Review how to use Execution policies.)

Set-ExecutionPolicy Unrestricted

(Allow unrestricted access.)

Running PowerShell from a Windows Client Computer

If you plan to run PowerShell from a Windows client computer rather than the console of the Office Communications Server 2007 R2 server itself, you must first install the administrative tools in Office Communications Server 2007 R2 on that particular Windows client.

This installation is not a problem with an x64-bit Windows client because the administrative tools in Office Communications Server 2007 R2 run on the x64 platform. However, an i386 Windows client requires a local installation of the 32-bit version of the administrative tools in Office Communications Server 2007 R2. The 32-bit version of the administrative tools in Office Communications Server 2007 R2 are located in the \support\i386 folder that is listed under the Office Communications Server 2007 R2 installation folder.

Step 1: PowerShell and WMI

Office Communications Server 2007 R2 uses the WMI interface to manage its levels of configuration. PowerShell has the ability to query the WMI interface and access the current instances of the Office Communications Server 2007 R2 classes. It has a list of approximately 120 MSFT_SIP* WMI classes that can be accessed through the PowerShell scripting environment. To view the complete list of the Office Communications Server 2007 R2 WMI classes, use the following PowerShell command from your PowerShell command prompt:

Get-WMIObject -List | Where {$_.__CLASS -like "MSFT_SIP*"}

If you want to take a quick look at your Office Communications Server 2007 R2-enabled user account information, use the following PowerShell command from your PowerShell command prompt:

Get-WMIObject -Query "Select * from MSFT_SIPESUserSetting Where PrimaryURI='SIP:samantha@contoso.com'"

The PowerShell Get-WMIobject -Query parameter allows us to use the WMI Query Language (WQL) to access information through the WMI interface. WQL is very similar to the Structured Query Language,(SQL); this similarity enhances WQL’s popularity with users who are familiar with using SQL.

Step 2: Use PowerShell and the Office Communications Server 2007 R2 Resource Kit

Now let’s take a quick look at those Microsoft Office Communications Server 2007 R2 Resource Kit PowerShell functions that I mentioned earlier. The following four steps will demonstrate how to access and begin to use the PowerShell functions that are provided by the Microsoft Office Communications Server 2007 R2 Resource Kit:

1. The files that are used to provide the Office Communications Server 2007 R2 functionality to the PowerShell command environment are located in the Microsoft Office Communications Server 2007 R2 Resource Kit CD's PowerShell_Scripts folder. Copy these files to a folder on your Windows client's hard disk that you will be performing your PowerShell scripting from; for example, c:\powershell.

2. Use the following PowerShell command from your PowerShell command prompt to load the library of Office Communications Server 2007 R2 functions into PowerShell on your Window's client:

   .  .\OCS-ALL.ps1
   

   (There are two spaces between the period (.) operators in the command.)

3. To view the now-loaded Office Communications Server 2007 R2 functions in the PowerShell command-line environment, use the following command from your PowerShell command prompt:

   Get-OCSFunction
   

4. To test access to the local Office Communications Server 2007 R2 installation, use the following OCS function to access the Pool's information:

   Get-OCSPool
   

Now that we have used the Get-OCSPool function to query the WMI interface for the Office Communications Server 2007 R2 Pool's information, which is stored in the domain's Active Directory Domain Services, we will be able to move forward with testing the combination of the OCS-All.ps1 functions along with the PowerShell command-line tools.

Step 3: Using the PowerShell Tee-Object Command

Piping is a command-line operator that directs the output of one PowerShell command to another PowerShell command for processing.

1. Send the display output of the Get-OCSUsers command to a text file by using the Tee-Object command from your PowerShell command prompt:

   Get-OcsUser | Tee-Object -file c:\powershell\get-ocsuser.txt
   

   For our example, we’ll use the following display output as shown in Table 1.

   Table 1. Tee-object command display output

   Display Name	Primary URI	Enabled	Line URI	UCEnabled
   Denise Smith	sip:denise@contoso.com	True	tel:+4255550101	True
   Samantha Smith	sip:samantha@contoso.com	True	tel:+4255550104	True
   Tony Smith	sip:tony@contoso.com	True	tel:+4255550105	True
   Jeff Smith	sip:jeff@contoso.com	True	tel:+4255550103	True

2. Browse to your PowerShell folder, and then open the get-ocsuser.txt file to view its contents.

Step 4: Use the PowerShell Export-CSV Command

Next, use the Get-OcsUser function along with the Export-Csv PowerShell command from your PowerShell command prompt to send the output of the Get-OCSUser command to a comma-separated values file. This information isn’t ported to your display. However, if you have Office Excel installed locally on your Windows client, you can review all the exported information in a neat spreadsheet format. If Office Excel is not available, you can view the information by using a text editor, such as Notepad:

Get-OcsUser | Export-Csv c:\powershell\get-ocsuser.csv

For more detailed information about exporting your OCS-function–related information to a variety of file formats, see the “Additional Information” section of this article.

Step 5: Using the PowerShell and the Office Communications Server 2007 R2 New-OcsUser Commands

Our next command will Office Communications Server-enable an Active Directory user object that has not yet been assigned to an Office Communications Server 2007 R2 Pool.

I’ll be testing the command with the new user account called Brian Smith as shown in Table 2. Run the PowerShell command from your PowerShell command prompt:

Get-adUser -filter "givenName=Bri*" | New-OcsUser -URI brian@contoso.com -homeServer (choose-ocspool)

Table 2. Brian Smith now appears in the display output

We have again used the Piping feature of PowerShell to provide the UserDN parameter to the New-Ocsuser command. The preceding Get-adUser -filter "givenName=Bri*" function provided us with the User parameter information that consists of the Active Directory Domain Services distinguished name for Brian’s user object. Now we can see Brian Smith as a new member of our Office Communications Server 2007 R2 Pool.

Now let's enable enhanced presence for the user object of our newly enabled Office Communications Server 2007 R2 user, Brian. For this demonstration, I am going to use the PowerShell Get-WMIObject command to enable enhanced presence for Brian's newly Office Communications Server-enabled user account. To perform this option, we will create an UpdateOCSUser.ps1 file that will contain the following information and be saved to your PowerShell folder as shown in the following script.

Paste the following PowerShell script into Notepad (or another editor), and then save the file as UpdateOCSUser.ps1 in your PowerShell folder:

#Get the OCS user.
$OCSUser = Get-WmiObject -Query "Select * from MSFT_SIPESUserSetting where PrimaryURI = 'sip:brian@contoso.com'" #Used to get OCS user object.
#Move user to new Pool.
# The system container example.
$OCSUser.HomeServerDN = "CN=LC Services,CN=Microsoft,CN=Pool01,CN=Pools,CN=RTC Service,CN=Microsoft,CN=System,DC=contoso,DC=com" 
#The configuration container example.
#$OCSUser.HomeServerDN = "CN=LC Services,CN=Microsoft,CN=OCSSTD,CN=Pools,CN=RTC Service,CN=Microsoft,CN=Configuration,DC=contosp,DC=com" 
#Enable the user for enhanced presence. This must be done before enabling for Unified Communications.
$OCSUser.EnabledForEnhancedPresence = $true 
#User access options.
$OCSUser.EnabledForFederation = $true #Enabled for federation.
$OCSUser.EnabledForInternetAccess = $true #Enabled for remote user access.
$OCSUser.PublicNetworkEnabled = $true #Enabled for public instant messaging (IM) connectivity.
#Telephony options.
$OCSUser.UCEnabled = $true
$OCSUser.LineURI = "tel:+14255550105"
$OCSUser.UCPolicy = "" #The string for Distinguished Name of the phone usage policy.
#Commit the changes.
$OCSUser.put() | out-null

With the previous text saved in a file named UpdateOCSuser.ps1 in the local PowerShell folder, the command can be executed as follows:

.  .\UpdateOCSUser.ps1 

(Make sure that there are two spaces between the period (.) operators.)

Now to view the results of the update, as shown in Table 3, run the following command:

Get-OCSUser

Table 3. Brian Smith’s phone number now appears in the display output

The reason for using the Get-WMIObject method this time is so that we can relate the differences between using the Microsoft Office Communications Server 2007 R2 Resource Kit OCS-ALL.ps1 function library and the more manual method.

Step 6: Performing a Lightweight Directory Access Protocol Query

Now here's a quick example of using PowerShell to perform a simple Lightweight Directory Access Protocol (LDAP) query for Office Communications Server 2007 R2-enabled users in the domain's Active Directory Domain Services. Paste the following PowerShell script into Notepad (or another editor), and then save the file in your PowerShell folder as Get-LDAPFilteredUsers.ps1:

#The following function will return a set of users who match the filter.
Function Get-LDAPFilteredUsers ($LdapFilter)
{
  $root = [ADSI]''
  $searcher = New-Object System.DirectoryServices.DirectorySearcher($root)
  $searcher.Filter = $LdapFilter
  $searcher.PageSize = 500
  $searcher.PropertiesToLoad.Add("dn") | Out-Null
  $searcher.PropertiesToLoad.Add("msRTCSIP-PrimaryHomeServer") | Out-Null
  $searcher.PropertiesToLoad.Add("msRTCSIP-PrimaryUserAddress") | Out-Null
  $users = $searcher.findall()
  $users
}
#Get the user group.
$PoolNameShort = "Pool01"
$users = Get-LDAPFilteredUsers "(&(&(&(objectCategory=User)(msRTCSIP-Optionflags=*)(msRTCSIP-PrimaryHomeServer=CN=LC Services,CN=Microsoft,CN=$PoolNameShort,CN=Pools,CN=RTC Service,CN=Microsoft,CN=System,DC=contoso,DC=com))))"

With the previous text saved in a file named Get-LdapFilteredUsers.ps1 in the local PowerShell folder, the command can be executed as follows:

.  .\Get-LdapFilteredUsers.ps1 

(Make sure that there are two spaces between the period (.) operators.)

The output information is stored in the $users variable. Just type $users at your PowerShell command prompt to view the results, as shown in Table 4, that are returned from the Get-LdapFilteredUsers function.

$users

Table 4. Results from the LdapFilteredUsers function

Step 7: Using PowerShell to Access Data from Various Data Sources

So far, we have been able to access our Office Communications Server 2007 R2 information by using WMI and LDAP queries from PowerShell. It can also access data that is stored in a variety of heterogeneous data sources, such as Microsoft SQL Server databases, Microsoft Office Access databases, and Microsoft Excel workbooks. Because Office Communications Server 2007 R2 stores its user and WMI class information in its databases in SQL Server, we can use PowerShell to access this information. Here are a couple of examples that will let us access data in the Office Communications Server 2007 R2 Real-time Communications (RTC) and RTCConfig databases. This time, we will add the QryRTCResources and QrySQLWMIClasses functions to our own function library—SQLPowershell.ps1. Also, we will borrow some of the functionality from the OCS-ALL.ps1 file so we can list the functions that our new library has to manage.

Paste the following PowerShell script into Notepad (or another editor), and then save the file in your PowerShell folder as SQLPowershell.ps1:

Function Get-ScriptPath
{ split-path $myInvocation.scriptName } # Borrowed from OCS-ALL.ps1.
Function QryRTCResources
{
#Create a Microsoft SQL Server connection string for the connection object by using integrated authentication.
$con = "server=host name of Microsoft SQL Server;database=RTC;Integrated Security=sspi"

#Create a command object that includes your query string.
$cmd = "Select TOP 100 * from Resource"
#Access the client libraries in SQL Server, and then create the data adapter and data table objects.
$da = new-object System.Data.SQLClient.SQLDataAdapter ($cmd, $con)
$dt = new-object System.Data.DataTable
#Fill the new local table with the imported data.
$da.fill($dt) | out-null
#Display the imported information.
$dt | Format-table -autosize
}

Function QrySQLWMIClasses
{
#Create a Microsoft SQL Server connection string for the connection object by using integrated authentication.
$con = "server= host name of Microsoft SQL Server;database=RTCConfig;Integrated Security=sspi"

#Create a command object that includes your query string.
$cmd = "Select Name from sysobjects where Name Like 'MSFT_SIP%'"

#Access the SQL Server client libraries, and then create the data adapter and data table objects.
$da = new-object System.Data.SQLClient.SQLDataAdapter ($cmd, $con)
$dt = new-object System.Data.DataTable

#Fill the new local table with the imported data.
$da.fill($dt) | out-null

#Display the imported information.
$dt | Format-table -autosize

}

#Add the next function above this line of text and below the last line."}"

#The information following was copied from the OCS-All,ps1 file, and then edited to reflect Qry* instead of *OCS*.

Function Get-QryFunction {dir Function:Qry* | sort @{expression={$_.name.split("-")[1] + $_.name.split("-")[0] }} | Select-Object name}

if ($myinvocation.line -match "^\.\s") {
dir Function:Qry* | measure-object | format-table -property count, @{expression={"Qry            Functionloaded"} } -HideTableHeaders -autosize  "Use Get-QryFunction to get a list"}
Else
{write-host -ForegroundColor red "No functions were loaded - you need to invoke with . scriptname "}

#I renamed ocsTypes.format.ps1xml to qryTypes.format.ps1xml—it must reside in the same folder.
Update-FormatData  (Join-Path (Get-scriptPath) "qryTypes.format.ps1xml")

Now we can access our OCS user SIP URI information that is stored in the Resource table of the RTC database by using the QryRTCResources PowerShell function and the list of tables that define the OCS WMI classes in the RTCConfig database. Here is a sample of the output from the user-defined PowerShell functions.

With the previous text saved in a file named SQLPowershell.ps1 in the local PowerShell folder, the command can be executed from your PowerShell command prompt as follows:

.  .\SQLPowershell.ps1
2 Qry Functions loaded

(Make sure that there are two spaces between the period (.) operators.)

Use Get-QryFunction to get a list:

Get-QryFunction --- View the functions in SQLPowershell.ps1

QryRTCResources and QrySQLWMIClasses are returned.

Now let’s run the QryRTCResources function from the PowerShell command prompt. The results are shown in Table 5.

QryRTCResources

Table 5. Results from the LdapFilteredUsers function

Now let’s run the QrySQLWMIClasses function from the PowerShell command prompt:

QrySQLWMIClasses

The results of the QrySQLWMIClasses function are shown in the following list:

• 
  MSFT_SIPAddressBookSetting

• 
  MSFT_SIPApplicationConfigSetting

• 
  MSFT_SIPCWAServerConfigSetting

• 
  MSFT_SIPClientPortSettings

• 
  MSFT_SIPClientUpdaterSetting

• 
  MSFT_SIPClientVersionFilterData

• 
  MSFT_SIPClientVersionFilterSetting

• 
  MSFT_SIPCommunicatorConfigSetting

• 
  MSFT_SIPDataComplianceSetting

• 
  MSFT_SIPDataMCUCapabilitySetting

• 
  MSFT_SIPDataMCUProxyServerData

• 
  MSFT_SIPDataMCUProxyServerPortSetting

• 
  MSFT_SIPDeviceUpdaterConfigSetting

• 
  MSFT_SIPDeviceUpdaterRules

• 
  MSFT_SIPDeviceUpdaterTestDevices

• 
  MSFT_SIPEsEmSetting

Step 8: Using PowerShell to Read from a File Object

Now that we are able to display the Office Communications Server WMI classes that are stored in the RTCConfig database, we will go one step further to see what makes up the definitions of these classes. To do this, we will create an additional PowerShell function named QryGetSQLWMIClassDefinitions and then add it to our SQLPowershell.ps1 library. This function will incorporate PowerShell's ability to read from a text file, the use of its foreach loop structure, and the typing of variables. To get started, you create a text file that contains the names of three of the WMI class that were previously listed—such as the following:

MSFT_SIPAddressBookSetting
MSFT_SIPDataMCUCapabilitySetting
MSFT_SIPPoolConfigSetting

Now save the file as sqlwmiclasses.txt in your PowerShell folder.

Copy the following PowerShell script into the SQLPowershell.ps1 function library between the closing brace (}) of the QrySQLWMIClasses function and the comment character (#):

Function QryGetSQLWMIClassDefinitions
{
#Notice the typing of the string variables as follows.

[string] $con
[string] $cmd
[string] $sqlwmiclass

#Here's how PowerShell implements the foreach loop structure. The driver of the loop is the text file entries of the OCS WMI classes.

foreach ($sqlwmiclass in get-content c:\powershell\sqlwmiclasses.txt)
{
$con = "server=<host name of Microsoft SQL Server>;database=RTCConfig;Integrated Security=sspi"

#Create a command object that includes your query string.

$cmd = "Select * from $sqlwmiclass"

$da = new-object System.Data.SQLClient.SQLDataAdapter ($cmd, $con)
$dt = new-object System.Data.DataTable

#Fill the new local table with the imported data.
$da.fill($dt) | out-null

#Display the imported information.
$sqlwmiclass #Display the name of each Office Communications Server WMI class as it is listed in the text file.
Write-Host "====================================="

#Using the tee-object command, we will port the Office Communications Server WMI class information to the display and to separate
#text files that will be named after the Office Communications Server WMI whose definition it contains.
$dt | tee-object -filepath c:\powershell\$sqlwmiclass 

 }
}

With the previous text saved in a file named SQLPowershell.ps1 in the local PowerShell folder, the command can be executed.

Now let's test our new addition to the SQLpowershell function library. Following is the information that the QryGetSQLWMIClassDefinitions function returns its output to in your display. Three new files will be created in the c:\powershell folder. Each file will contain the information for an instance of the Office Communications Server WMI class definition that it’s named after:

.  .\SQLpowershell.ps1 
 3 Qry Functions loaded

(Make sure that there are two spaces between the period (.) operators.)

Use Get-QryFunction to get an updated list of the SQLpowershell.ps1 functions:

Get-QryFunction

The Get-QryFunction list contains the following functions:

• 
  QryGetSQLWMIClassDefinitions

• 
  QryRTCResources

• 
  QryGetSQLWMIClassDefinitions

Now, from the PowerShell command prompt, we can run the new QryGetSQLWMIClassDefinitions function and then review its results:

QryGetSQLWMIClassDefinitions

The following results are returned for the MSFT_SIPAddressBookSetting, MSFT_SIPDataMCUCapabilitySetting, and MSFT_SIPPoolConfigSetting classes. The results can be seen in Table 6, Table 7, and Table 8, respectively.

Table 6. MSFT_SIPAddressBookSetting results

Table 7. MSFT_SIPDataMCUCapabilitySetting results

Table 8. MSFT_SIPPoolConfigSetting results

Step 9: Use PowerShell to Prompt Users to Input Parameters

Most of the functions in the OCS-ALL.ps1 file require that we pass at least one parameter to them as a value that the function’s conditional code will use as criteria to formulate the returned value of the function.

Here's a brief PowerShell script example of how to design the following:

• A function that will accept an Office Communications Server 2007 R2-enabled user's Session Initiation Protocol (SIP) URI as criteria

• A way to provide the user with all the information on that user's Office Communications Server 2007 R2-enabled configuration

The following PowerShell script will need to be saved as the contents of WMIpowershell.ps1 file. The QryWMIForSipUser function will be designed to prompt the user to type a valid SIP URI, such as denise@contoso.com. This is done by using the PowerShell command Read-Host, which will allow us to define the prompt and then accept the input string (what we are prompted to input) into the script. The function will return the output from the Get-WMIObject -Query command to the Export-Csv command so that the Office Communications Sever 2007 R2 user’s information is saved to a file, such as denise@contoso.com.csv. The QryWMIForSipUser function will use a Do While loop structure that will continually prompt the user for the next Office Communications Server 2007 R2 user’s SIP URI until ENTER is pressed. Also, the QryWMIForSipUser function provides an introduction into using the string concatenation operator (+) to build the Office Communications Server 2007 R2 user URI and file path information.

Paste the following PowerShell script into the WMIPowershell.ps1 function library between the closing brace (}) of the QrySQLWMIClasses function and the comment character (#):

Function Get-ScriptPath
{split-path $myInvocation.scriptName}
Function QryWMIForSIPUser
{
#Strong typing of variables.
[string] $SipURI
[string] $FileName
[WMI] $SipUserInfo
do #Use a do while loop structure for continuous processing.
 {
     $SipURI = Read-Host "Please Enter a valid user SIP URI" 
     $FileName = $SipUri
     if ($SipURI -ne "")
     {$SipURI = "SIP:" + $SipURI
     $SipUri = "'" + $SipUri + "'" #String concatenation comes into play here to build the SIP URI.
$SipUserInfo = Get-WMIObject -Query "Select * from MSFT_SIPESUserSetting Where PrimaryURI = $SipURI"
$FileName = "c:\powershell\" + $FileName + ".csv" #String concatenation comes into play here to build the file path.
$FileName
$SipUserInfo | Export-Csv $FileName
     }
 }
while ($SipURI -ne "") #Continue looping while $SipURI is not equal to the empty string.
} 
Function Get-QryFunction {dir Function:Qry* | sort @{expression={$_.name.split("-")[1] + $_.name.split("-")[0] }} | Select-Object name}
if ($myinvocation.line -match "^\.\s") { dir Function:Qry* | measure-object | format-table -property count, @{expression={"Qry Functions loaded"} } -HideTableHeaders -autosize "Use Get-QryFunction to get a list"}
Else {write-host -ForegroundColor red "No functions were loaded - you need to invoke with . scriptname "}
Update-FormatData  (Join-Path (Get-scriptPath) "qryTypes.format.ps1xml")

Step 10: Use PowerShell to Validate User Parameter Input

The QryWMIForSIPUser function works well until we enter a non-valid SIP URI for one of our Office Communications Server 2007 R2 users who we are gathering information on. If the SIP URI cannot be located by the Get-WMI -Query command, a Null value is returned to the $SipUserInfo variable and the Export-Csv command fails. We need a way to inform the user that they have entered the wrong information into the program. The PowerShell built-in error handling routines will come in handy along with using a conditional structure. We can check $SipUserinfo for a Null value, and then use that condition to bypass the Export-Csv command while providing some useful output to the display.

Here's an updated version of the QryWMIForSIPUser function that reflects the changes that we just discussed.

Function QryWMIForSIPUser
{
[string] $SipURI
[string] $FileName
[WMI] $SipUserInfo

#If an error occurs, move to the next line of code and then provide the run-time exception to the display.
#This will help ensure the operation of the script if a run-time error occurs.
#The other parameters for $ErrorActionPreference are "Stop" and "SilentlyContinue".

$ErrorActionPreference = "Continue" 

do
  {
$SipURI = Read-Host "Please enter a valid user SIP URI"
$FileName = $SipUri
    if ($SipURI -ne "")
        {$SipURI = "SIP:" + $SipURI
        $SipUri = "'" + $SipUri + "'"

$SipUserInfo = Get-WMIObject -Query "Select * from MSFT_SIPESUserSetting Where PrimaryURI = $SipURI"
         if ($SipUserInfo -eq $NULL) #Let's check for a null value being passed to $SipUserInfo.
         {Write-Host -ForegroundColor red "Enter a valid SIP URI like denise@contoso.com"}
        else
        {$FileName = "c:\powershell\" + $FileName + ".csv"
$FileName
$SipUserInfo | Export-Csv $FileName
         }
    }
  }
while ($SipURI -ne "")
}