Ten Steps to PowerShell Scripting with Office Communications Server 2007 R2
Microsoft Office Communications Server 2007 and Microsoft Office Communications Server 2007 R2 will reach end of support on January 9, 2018. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.
Windows PowerShell can be used as a management tool for Microsoft Office Communications Server 2007 R2. PowerShell is one of most versatile scripting environments available on the market today. This powerful new cross-platform scripting tool can be used with all versions of Office Communications Server as a configuration alternative to the administrative tools in Office Communications Server. As a cross-platform scripting language, PowerShell is cohesive with the following:
Microsoft Active Directory directory service
Heterogeneous data sources such as Microsoft SQL Server
Microsoft Office products such as Microsoft Office Access, Microsoft Office Excel, and Microsoft Office Word
This makes the adaptability of PowerShell to Microsoft enterprise-level environments a sought-after experience for administrators. It takes just a few easy steps to get started using PowerShell with Office Communications Server 2007 R2. Reading this article is a good way to get started using PowerShell with Office Communications Server 2007 R2.
Author: Michael Adkins
Publication date: May 2010
Product version: Microsoft Office Communications Server 2007 R2
Windows PowerShell is the Microsoft command-line scripting environment. PowerShell can be used as a powerful tool for Microsoft Windows Server 2008, Microsoft Windows Server 2003, and application administration. One of the many uses PowerShell has as a scripting tool is with Microsoft Office Communications Server 2007 R2 administration. By design, the PowerShell command-line scripting tool can query and perform updates to the Active Directory directory service and the Windows Management Instrumentation (WMI) interface. And for reporting purposes, the scripting tool can also utilize heterogeneous data sources, such as Microsoft SQL Server, Microsoft Office Access, and Microsoft Office Excel. This article provides you with some simple steps that demonstrate how easy it is to get started using Windows PowerShell with Office Communications Server 2007 R2.
Download PowerShell
Obtaining your copy of the latest version of PowerShell is simple—just download the version of PowerShell that’s right for you from Scripting with Windows PowerShell at https://go.microsoft.com/fwlink/?linkid=111264.
Note
For detailed information about getting started with PowerShell, see the “Additional Information” section of this article.
Using PowerShell with Office Communications Server 2007 R2
Before we use PowerShell with Office Communications Server 2007 R2, we need to take a look at some important issues. They are covered in this section.
Set the PowerShell Execution Policy
You’ll need to set the PowerShell Execution Policy levels. They are as follows:
Restricted
Unrestricted
AllSigned
RemoteSigned
Note
To effectively use PowerShell throughout this demonstration, create a folder on your Windows client that will be used to manage your PowerShell content. For the purpose of this demonstration, I am using PC c:\powershell.
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.
Important
The Microsoft Office Communications Server 2007 R2 Resource Kit Office Communications Server ALL.ps1 function library contains several functions that can provide updates to your Office Communications Server 2007 R2 environment. Use these functions with caution because they can cause unwanted updates to your Office Communications Server 2007 R2 environment.
Use PowerShell Scripting with Office Communications Server 2007 R2
The following ten steps show you how to use PowerShell scripting with Office Communications Server 2007 R2.
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:
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.
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.)
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
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.
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
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.
Note
This command performs an update to a user object in your domain's Active Directory Domain Services.
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
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 |
Brian Smith |
sip:brian@contoso.com |
True |
False |
|
Jeff Smith |
sip:jeff@contoso.com |
True |
tel:+4255550103 |
True |
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.
Note
The Get-WMIObject command performs an update to a user object in your domain's Active Directory Domain Services.
Paste the following PowerShell script into Notepad (or another editor), and then save the file as UpdateOCSUser.ps1 in your PowerShell folder:
Note
The following script sample has code that wraps to the next line of the document. In addition, the script performs updates for the system configuration container installation. If you are using a configuration container installation, un-comment and then comment (#) the code where needed.
#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
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 |
Brian Smith |
sip:brian@contoso.com |
True |
tel:+4255550106 |
True |
Jeff Smith |
sip:jeff@contoso.com |
True |
tel:+4255550103 |
True |
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
Path | Properties |
---|---|
LDAP://CN=Denise Smith,CN=Users,DC=contoso,DC=com |
{msrtcsip-primaryuseraddress, msrtcsip-primaryhomeserver |
LDAP://CN=Jeff Smith,CN=Users,DC=contoso,DC=com |
{msrtcsip-primaryuseraddress, msrtcsip-primaryhomeserver |
LDAP://CN=Samantha Smith,CN=Users,DC=contoso,DC=com |
{msrtcsip-primaryuseraddress, msrtcsip-primaryhomeserver |
LDAP://CN=Tony Smith,CN=Users,DC=contoso,DC=com |
{msrtcsip-primaryuseraddress, msrtcsip-primaryhomeserver |
LDAP://CN={F56586A3-AF61-4FDC-8570-0AF47B95E64A},CN=Appl |
{msrtcsip-primaryuseraddress, msrtcsip-primaryhomeserver |
LDAP://CN={F55802CC-0E0F-4DBF-A342-4BA3ADBA5BC5},CN=Appl |
{msrtcsip-primaryuseraddress, msrtcsip-primaryhomeserver |
LDAP://CN={7A7D5EBB-69DA-4ED3-A9A4-31A4796B2DED},CN=Appl |
{msrtcsip-primaryuseraddress, msrtcsip-primaryhomeserver |
LDAP://CN=Brian Smith,CN=Users,DC=contoso,DC=com |
{msrtcsip-primaryuseraddress, msrtcsip-primaryhomeserver |
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
Resourceid | UserAtHost |
---|---|
1 |
RtcApplication-F56586A3-AF61-4FDC-8570-0AF47B95E64A@contoso.com |
2 |
RtcApplication-7A7D5EBB-69DA-4ED3-A9A4-31A4796B2DED@contoso.com |
3 |
RtcApplication-7A7D5EBB-69DA-4ED3-A9A4-31A4796B2DED@contoso.com |
24 |
denise@contoso.com |
25 |
samantha@contoso.com |
26 |
tony@contoso.com |
27 |
brian@contoso.com |
28 |
jeff@contoso.com |
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
Note
I have removed over half of the OCS WMI classes that would usually be displayed to make room for the addition of the next function.
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
InstanceID |
: d265a402-bd08-4bcb-beb3-cc7afbd47c08 |
RunTime |
: 130 |
DaysToKeep |
: 30 |
MaxDeltaFileSizePercentage |
: 1250 |
SynchronizePollingIntervalSecs |
: 300 |
SynchronizeNow |
: False |
UseNormalizationRules |
: True |
IgnoreGenericRules |
: False |
PartitionOutputByOU |
: False |
WebServiceEnabled |
: True |
OutputLocation |
: \\servername\abs |
InternalURL |
: https://pool01.contoso.com/Abs/Int/Handler |
ExternalURL |
: https://meeting.contoso.com/Abs/Ext/Handler |
Table 7. MSFT_SIPDataMCUCapabilitySetting results
InstanceID |
: 086d006c-8672-4a73-a488-3f9346d4f98c |
ContentStorageLimit |
: 500 |
HandoutsStorageLimit |
: 150 |
ContentExpirationGracePeriod |
: 14 |
MeetingPresentationContentLocation |
: \\servername\meeting |
MeetingMetadataLocation |
: \\servername\metadata |
InternalClientContentDownloadURL |
: https://pool01.contoso.com/etc/place/null |
ExternalClientContentDownloadURL |
: https://meeting.contoso.com/etc/place/null |
InMeetingHelpURL |
: http://r.office.microsoft.com/r/rlidLiveMeeting |
Table 8. MSFT_SIPPoolConfigSetting results
InstanceID |
: 06bed421-5575-49e6-8350-d9c13c1a12b9 |
DNATMode |
: False |
ServerQoSEnabled |
: False |
AllowAnonUserConfDialOut |
: True |
MediaPortRangeFrom |
: 49152 |
MediaPortRangeTo |
: 65535 |
MaxVideoReceiveCapabilityAllowed |
: VGA-600K |
ApplicationDataLocation |
: \\servername\applications |
LanguageIds |
: 1033 |
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 "")
}
Summary
PowerShell offers us a very versatile scripting platform whose features have the ability to access data from a range of sources from WMI to the contents of a text file. These features make PowerShell a great tool to troubleshoot and analyze your Office Communications Server 2007 R2 infrastructure. The Microsoft Office Communications Server 2007 R2 Resource Kit PowerShell functions provide us with a powerful set of scripts that can be used to analyze and perform updates to an Office Communications Server 2007 R2 environment.
Important
If you are interested in using the Microsoft Office Communications Server 2007 R2 Resource Kit PowerShell functions, look them over carefully. Before using them to perform any updates to your Office Communications Server 2007 R2 environment, test them in your Office Communications Server 2007 R2 lab to make sure that you fully understand the impact of the updates that they will perform to your Office Communications Server environment.
I hope that this brief set PowerShell examples helps you get on your way to scripting with PowerShell and Office Communications Server 2007 R2.
Additional Information
Windows PowerShell Owner’s Manual at https://go.microsoft.com/fwlink/?LinkId=192606.
Windows PowerShell Quick Reference at https://go.microsoft.com/fwlink/?LinkId=192607.
Windows PowerShell 2.0 CTP, the Windows PowerShell Debugger at https://go.microsoft.com/fwlink/?LinkID=192610.
Scripting with Windows PowerShell 2.0 CTP at https://go.microsoft.com/fwlink/?LinkId=192611.
Windows® PowerShell 2.0 – Screencast at https://go.microsoft.com/fwlink/?LinkId=192612.
PowerShell Scriptomatic at https://go.microsoft.com/fwlink/?LinkId=192613.
The Power of Variables at https://go.microsoft.com/fwlink/?LinkId=192614.
Communications Server Resources
Visit the Communications Server main page at https://go.microsoft.com/fwlink/?LinkId=132607.
View the complete Communications Server documentation library at https://go.microsoft.com/fwlink/?LinkId=132106.
Download the Communications Server content as Word documents at https://go.microsoft.com/fwlink/?LinkId=133609.
Download the Communications Server documentation as a compiled help file at https://go.microsoft.com/fwlink/?LinkId=160355. (Scroll down to the Additional Information section and download OCSDocumentation.chm.)
Read weekly articles for Communications Server IT professionals on NextHop at https://go.microsoft.com/fwlink/?LinkId=181907.
Read NextHop articles in the Technical Library at https://go.microsoft.com/fwlink/?LinkId=185344.
Subscribe to NextHop feeds on the OPML List for NextHop page at https://go.microsoft.com/fwlink/?LinkId=185345.
Read weekly articles for Communications Server developers on UCode at https://go.microsoft.com/fwlink/?LinkId=177892.
Follow tweets from the Communications Server team at https://go.microsoft.com/fwlink/?LinkId=167909.
We Want to Hear from You
To give us feedback about this article or to propose a topic for an article, e-mail us at NextHop@microsoft.com.
You can also send us a tweet at https://www.twitter.com/DrRez.