16 Managing the Instant Messaging and Presence Service

16.2.1 Microsoft Office Communications Server (OCS) Prerequisites

This section describes the Microsoft Office Communications Server 2007 (OCS) prerequisites as the presence server for the Instant Messaging and Presence service.

This section includes the following subsections:

• Section 16.2.1.1, "OCS - Installation"

• Section 16.2.1.2, "OCS - Configuration"

• Section 16.2.1.3, "OCS - Security Considerations"

16.2.1.2 OCS - Configuration

To use Microsoft OCS 2007 as the presence server for the IMP service, you must deploy the Oracle WebCenter proxy for Microsoft OCS 2007 in one of two topologies:

• Simple Deployment – All components reside on the same box

• Remote Deployment – The proxy application and Microsoft OCS reside on separate boxes

16.2.1.2.1 Simple Deployment

In this topology, the WebCenter Proxy Application is deployed in the Internet Information Services (IIS) server hosted on the OCS box.

1. Install Microsoft Unified Communications Managed API (UCMA) 2.0 on the OCS box.

   For detailed information, see Section 16.2.1.2.6, "Installing UCMA v2.0."

2. Deploy the WebCenter Proxy Application on the IIS server. The WebCenter Proxy Application provides web services for interacting with the OCS server and sending/receiving information. WebCenter talks to these web services and presents the data.

   For detailed information, see Section 16.2.1.2.7, "Installing the WebCenter Proxy Application."

16.2.1.2.2 Remote Deployment

In this topology, the WebCenter Proxy Application is deployed on an IIS server remote to the OCS box. That is, the IIS server and the OCS server are hosted on separate machines.

Because the WebCenter Proxy Application is hosted on a remote box, you must set up a trust between the application and the OCS server. This is known as provisioning an application. Provisioning is done through the Application Provisioner utility shipped with Microsoft UCMA v2.0. For more details, see http://msdn.microsoft.com/en-us/library/dd253360%28office.13%29.aspx.

Figure 16-1 provides an overview of the steps (including installing UCMA v2.0) to be performed on different deployment entities.

Figure 16-1 Microsoft OCS Configuration - Remote Deployment

Description of "Figure 16-1 Microsoft OCS Configuration - Remote Deployment"

The details of these steps are described in the following sections.

16.2.1.2.3 Building Application Provisioner

This section lists the steps Microsoft provides for provisioning other IIS servers to access OCS.

1. Install Visual Studio 2008 on any developer box (not necessarily IIS/OCS).

2. Install UCMA version 2.0 on the same box following the steps in Section 16.2.1.2.6, "Installing UCMA v2.0." The Application Provisioner application comes with the UCMA SDK.

3. Go to the directory Sample Applications\Collaboration\ApplicationProvisioner under the location where you installed UCMA Core (for example, C:\Program Files\Microsoft Office Communications Server 2007 R2\UCMA SDK 2.0\UCMACore\Sample Applications\Collaboration\ApplicationProvisioner).

4. The directory contains the Application Provisioner application. Build the application using Visual Studio 2008. This generates the ApplicationProvisioner.exe file.

5. Copy the executable file to the OCS box.

16.2.1.2.4 Provisioning WebCenter Proxy Application on OCS Server

1. Install UCMA v2.0 core libraries on the OCS box. Follow the same steps in Section 16.2.1.2.6, "Installing UCMA v2.0," except that after installing Visual C++ 2008 Redistributable, run OCSCore.msi. This installs the WMI classes required to provision an application.

2. Run the ApplicationProvisioner.exe file, generated in the previous section. This launches the Application Provisioner dialog.

3. In the Application Provisioner dialog, enter WebCenterProxyApplication as the name of your application for the Application name, and then click Find or Create.

4. In the Create Application Pool dialog, select the Office Communications Server pool for your application in the OCS Pool Fqdn list. For Listening port, enter the listening port for your application (for example, 6001). For Application server Fqdn, enter the fully qualified domain name (FQDN) of the computer on which the application is deployed. (This is the IIS box.)

   If the application is deployed on two or more computers, then select the Load balanced application checkbox, and for Load balancer Fqdn, enter the FQDN of the load balancer.

5. The application pool now appears in the Application Provisioner dialog. Double-click the server entry. The View Server dialog appears. Note the information shown there; that is, Server FQDN, port, and GRUU.

6. Create a certificate on the OCS server with the subject name as the Server FQDN noted in the previous step using the Office Communications Server Certificate Wizard. This certificate is used to authorize the requests coming from the IIS server.

7. After the certificate is created, view the certificate. On the Details tab click Copy to File. This launches the Certificate Export Wizard. Export the certificate with the private key to a file. This creates a .pfx (Personal Information Exchange) file with the certificate name.

16.2.1.2.5 IIS Server Configuration

Because the IIS server hosts the WebCenter Proxy Application in the remote deployment scenario, use the information from the previous section to make it a trusted authority.

1. Install the certificate issued by the OCS server with the private key: Copy the .pfx file generated in step 7 under section "Provisioning WebCenter Proxy Application on OCS Server" to the IIS box, and double-click it. This launches the Certificate Import wizard. Import the certificate in Personal Folder under LOCAL_MACHINE.

2. Give permission to IIS_WPG user for reading the certificate. This is required so that the IIS server has appropriate read access on the certificate. This could be done using a utility provided by Microsoft called Windows HTTP Services Certificate Configuration Tool (http://www.microsoft.com/downloads/details.aspx?familyid=c42e27ac-3409-40e9-8667-c748e422833f&displaylang=en). Download the utility and install it. This creates an executable called winhttpcertcfg.exe. Go to the install location and run the following command to grant permission:

   winhttpcertcfg.exe -g -c LOCAL_MACHINE\MY -s "<certificate-name>" -a "IIS_WPG"
   

3. Make an entry in C:/WINDOWS/system32/drivers/etc/hosts for the pool name of the OCS server as follows:

   <ip-address-of-ocs-box> <poolname-of-ocs-box>
   

   For example:

   10.177.252.146 pool01.example.com
   

4. Because the IIS server hosts the WebCenter Proxy Application, install Microsoft UCMA v2.0 on it.

   For detailed information, see Section 16.2.1.2.6, "Installing UCMA v2.0."

5. After UCMA is installed, deploy the WebCenter Proxy Application on the IIS server. WebCenter Proxy Application provides web services for interacting with OCS server and sending/receiving information. WebCenter talks to these web services and presents the data.

   For detailed information, see Section 16.2.1.2.7, "Installing the WebCenter Proxy Application."

6. Go to the location where WebCenter Proxy Application was extracted. Open Web.config and edit the appSettings XML node to add the values noted in Step 7 in previous section. Ensure to set value for RemoteDeployment to true.

   For example, the appsettings XML node should look somewhat like this.

   <appSettings>
     <add key="ApplicationName" value="WebCenterProxyApplication"/>
     <add key="RemoteDeployment" value="true"/>
     <add key="ApplicationServerFQDN" value="iis.server.com"/>
     <add key="ApplicationServerGRUU" value="sip:iis.server.com@EXAMPLE.COM;gruu;opaque=srvr:WebCenterProxyApplication:7mhSo94PlUK-5Q2bKPLyMAAA"/>
     <add key="ApplicationServerPort" value="6001"/>
   </appSettings> 
   

The trust is established and the WebCenter Proxy Application can talk to OCS server.

16.2.1.2.6 Installing UCMA v2.0

Microsoft Unified Communications Managed API v2.0 (UCMA) is an endpoint API that allows advanced developers to build server applications that can interact with the OCS environment.

In a simple deployment, the UCMA is installed on the same box as OCS. In a remote deployment, the OCS core libraries are installed on the OCS box, and the UCMA is installed on the IIS (proxy) box.

1. Download UCMA v2.0 from the following location:

   • For OCS2007 R1 installation (32 bit): http://www.microsoft.com/downloads/details.aspx?FamilyID=768efa33-6606-4b2b-809a-6c69274621d3&displaylang=en

     Download and run the UcmaSDKWebDownload.msi file. This extracts set up files to the folder C:\Microsoft Unified Communications Managed API 2.0 SDK Installer package\i386.

   • For OCS2007 R2 installation (64 bit): http://www.microsoft.com/downloads/details.aspx?FamilyID=b20967b1-6cf5-4a4b-b7ae-622653ac929f&displaylang=en

     Download and run the UcmaSDKWebDownload.msi file. This extracts set up files to the folder C:\Microsoft Unified Communications Managed API 2.0 SDK Installer package\amd64.

2. Go to the directory (where the files from the previous step were extracted) and run vcredist_x86.exe. This installs run-time components of Visual C++ Libraries required for UCMA APIs. Go to directory called Setup and run UcmaRedist.msi. This installs the UCMA 2.0 assemblies in the GAC.

16.2.1.2.7 Installing the WebCenter Proxy Application

1. Extract owc_ocs2007.zip from the companion CD. This creates a directory named OCSWebServices.

2. Open the Internet Information Services (IIS) Manager.

3. Expand the server node and then Web Sites in the Internet Information Services (IIS) Manager.

4. Right-click Default Web Site, choose New, and then select Virtual Directory to create a site for the Oracle RTC Web service. The Virtual Directory Creation Wizard displays. Click Next.

5. Enter an alias for the virtual directory in the Alias field, for example RTC.

6. Enter the path to the directory extracted from owc_ocs2007.zip file. If you had extracted the zip file in C:\, then the path supplied should be C:\OCSWebServices. Alternatively, use the Browse button to navigate to that directory. Click Next.

7. Ensure that the virtual directory has the Read, Execute, and Browse privileges. Click Next.

8. Click Finish. The newly created virtual directory appears under Default Web Site in the Internet Information Services (IIS) Manager window.

9. Right-click the newly created virtual directory for the Oracle RTC Web service, and then choose Properties to open the Properties dialog.

10. In the Virtual Directory tab, under Application settings, click Create. Notice that the button label changes to Remove, and the name of your newly created virtual directory appears in the Application name field.

11. Select Scripts and Executables from the Execute permissions dropdown list.

12. Under the ASP.NET tab, select the ASP.NET version as 2.0 or higher from the ASP.NET version dropdown list. IIS should be configured to consume ASP.NET 2.0 applications. Click OK.

13. Test the Web service by accessing the Web site from the following URL format: http://localhost/default_website/OCSWebService.asmx.

    where default_website is the virtual directory you created for the Oracle RTC Web service

    For example:

    http://localhost/RTC/OCSWebService.asmx

16.2.2 Microsoft Live Communications Server (LCS) Prerequisites

This section describes the Microsoft Live Communications Server 2005 (LCS) prerequisites as the presence server for the Instant Messaging and Presence service.

This section includes the following subsections:

• Section 16.2.2.1, "LCS - Installation"

• Section 16.2.2.2, "LCS - Configuration"

• Section 16.2.2.3, "LCS - Security Considerations"

16.2.3 Oracle WebLogic Communications Server (OWLCS) Prerequisites

This section describes Oracle WebLogic Communications Server (OWLCS) prerequisites as the presence server for the Instant Messaging and Presence service.

This section includes the following subsections:

• Section 16.2.3.1, "OWLCS - Installation"

• Section 16.2.3.2, "OWLCS - Configuration"

• Section 16.2.3.3, "OWLCS - Security Considerations"

• Section 16.2.3.4, "OWLCS - Limitations"

16.3.1 Registering Instant Messaging and Presence Servers Using Fusion Middleware Control

To register a presence server connection:

1. Log in to Fusion Middleware Control and navigate to the home page for the WebCenter application. For more information, see:

   • Section 6.2, "Navigating to the Home Page for WebCenter Spaces"

   • Section 6.3, "Navigating to the Home Page for WebCenter Portal Applications"

2. Do one of the following:

   • For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.

   • For WebCenter Portal applications - From the Application Deployment menu, choose WebCenter > Service Configuration.

3. From the list of services on the WebCenter Service Configuration page, choose Instant Messaging and Presence.

4. To connect to a new presence server, click Add (Figure 16-6).

   Figure 16-6 Configuring Instant Messaging and Presence Services

   
   

5. Enter a unique name for this connection, specify the presence server type, and indicate whether this connection is the active (or default) connection for the application (Table 16-1).

   Table 16-1 Instant Messaging and Presence Connection - Name

   Field	Description
   Name	Enter a unique name for the connection. The name must be unique (across all connection types) within the WebCenter application.
   Connection Type	Specify the type of presence server: Microsoft Live Communications Server (LCS) Microsoft Office Communications Server 2007 (OCS) Oracle WebLogic Communications Server (OWLCS) Out-of-the-box, three presence connection types are available— LCS, OCS, and OWLCS.
   Active Connection	Select to use this connection in the WebCenter application for instant messaging and presence services. While you can register multiple presence server connections for a WebCenter application, only one connection is used by the IMP service—the default (or active) connection.

   
   

6. Enter connection details for the server hosting instant messaging and presence services (Table 16-2).

   Table 16-2 Instant Messaging and Presence Connection - Connection Details

   Field	Description
   Server URL	Enter the URL of the server hosting instant messaging and presence services. For example: http://myocshost.com:8888
   Policy URI	(OWLCS Only) Specify the URI to the WS-Security policy that is required for authentication on the Oracle WebLogic Communication Server. Specify oracle/wss11_saml_token_with_message_protection_client_policy when OWLCS is WS-Security enabled.
   Authentication Method	(OWLCS Only) Specify how to authenticate users against the instant messaging and presence server. Select from: Identity Propagation - Select this option if you want the application and OWLCS to use the same user identity. External Application - Use an external application to authenticate users against the instant messaging and presence server. Select this option to use public, shared, or mapped credentials. If an external application is used for authentication, use the Associated External Application list to identify the application. If the application you want is not listed, select Create New... to define the external application.
   User Domain	(OCS Only) Enter the name of the Active Directory domain (on the Microsoft Office Communications Server) that is associated with this connection. The user domain is mandatory for OCS connections. Refer to Microsoft Office Communications Server documentation for details.
   Pool Name	(LCS and OCS Only) Enter the name of the pool that is associated with this connection. The pool name is mandatory for LCS and OCS connections. Refer to Microsoft Live Communications Server or Microsoft Office Communications Server documentation for details on the pool name.
   Associated External Application	Associate the instant messaging and presence server with an external application. External application credential information is used to authenticate users against the instant messaging and presence server. An external application is mandatory for LCS and OCS connections. You can select an existing external application from the list, or click Create New to configure a new external application. The external application you configure for the Instant Messaging and Presence service must use the POST authentication method, and specify an additional field named Account (Name property) that is configured to Display to User (checked). For more information, see Chapter 25, "Managing External Applications."
   Connection Timeout (in seconds)	Specify a suitable timeout for the connection. This is the length of time (in seconds) the WebCenter application waits for a response from the presence server before issuing a connection timeout message. The default is -1 which means that the service default is used. The service default is 10 seconds.

   
   

7. Sometimes, additional parameters are required to connect to the presence server.

   If WS-Security is enabled on this connection, add a property named recipient.alias and enter the alias used to import the OWLCS certificate. Ensure that this value is unique and is not used by some other service. If no alias name is supplied, then the default value is used (webcenter_owlcs).

   Table 16-3 lists additional parameters.

   Table 16-3 Additional IMP Connection Properties

   Additional Connection Property	Valid IMP Servers	Description
   presence.url	OWLCS	URL to the OWLCS Presence service. Required if the OWLCS Presence service is deployed on a separate node. When no value is specified, the Server URL property is used.
   contacts.url	OWLCS	URL to the OWLCS Contact Management service. Required if the OWLCS Contact Management service is deployed on a separate node. When no value is specified, the Server URL property is used.
   call.url	OWLCS	URL to the OWLCS Third Party Call service. Required if the OWLCS Third Party Call service is deployed on a separate node. When no value is specified, the Server URL property is used.
   call.method	OWLCS	Third party call method. Valid values are: sip and pstn. When set to sip, third party calls are forwarded to Oracle Communicators. When set to pstn, calls are forwarded to PSTN telephones (contact.number.attribute provides the phone number).
   call.domain	OWLCS	Domain name of the PSTN gateway. Required when the call.method is pstn. If no domain name is supplied, the connection's Domain value is used.
   contact.number.attribute	OWLCS	User profile attribute used to store users' phone numbers. The default attribute is BUSINESS_PHONE. Required when the call.method is pstn.
   recipient.alias	OWLCS	Alias used to import the OWLCS certificate. The value must be unique and must not be used by another service. If no alias name is supplied, the application uses the default value webcenter_owlcs.

   
   

   If additional parameters are required to connect to the presence server, expand Additional Properties and enter details as required (Table 16-4).

   Table 16-4 Instant Messaging and Presence Connection - Additional Properties

   Field	Description
   Add	Click Add to specify an additional connection parameter: Name -Enter the name of the connection property. Value - Enter the default value for the property. Is Property Secured - Indicate whether encryption is required. When selected, the property value is stored securely using encryption. For example, select this option to secure the admin.password property where the value is the actual password.
   Delete	Click Delete to remove a selected property. Select the correct row before clicking Delete. Note: Deleted rows appear disabled until you click OK.

   
   

8. Click OK to save this connection.

9. To start using the new (active) connection you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

16.3.2 Registering Instant Messaging and Presence Servers Using WLST

Use the WLST command createIMPConnection to create a presence server connection. For command syntax and examples, see the section, "createIMPConnection" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

To configure the Instant Messaging and Presence service to actively use a new IMP connection, set default=true. For more information, see Section 16.4.2, "Choosing the Active Connection for Instant Messaging and Presence Using WLST."

16.4.1 Choosing the Active Connection for Instant Messaging and Presence Using Fusion Middleware Control

To change the active connection:

1. Log in to Fusion Middleware Control and navigate to the home page for the WebCenter application. For more information, see:

   • Section 6.2, "Navigating to the Home Page for WebCenter Spaces"

   • Section 6.3, "Navigating to the Home Page for WebCenter Portal Applications"

2. Do one of the following:

   • For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.

   • For WebCenter Portal applications - From the Application Deployment menu, choose WebCenter > Service Configuration.

3. From the list of services on the WebCenter Services Configuration page, select Instant Messaging and Presence.

   The Manage Instant Messaging and Presence Connections table indicates the current active connection (if any).

4. Select the connection you want to make the active (or default) connection, and then click Edit.

5. Select the Active Connection checkbox.

6. Click OK to update the connection.

7. To start using the new (active) connection you must restart the managed server on which the WebCenter application is deployed. See Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

16.4.2 Choosing the Active Connection for Instant Messaging and Presence Using WLST

Use the WLST command setIMPConnection with default=true to activate an existing presence server connection. For command syntax and examples, see the section, "setIMPConnection" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

To disable a presence server connection, either delete it, make another connection the 'active connection' or use the removeIMPServiceProperty command:

removeIMPServiceProperty('appName='webcenter', property='selected.connection')

Using this command, connection details are retained but the connection is no longer named as an active connection. For more information, see the section, "removeIMPServiceProperty" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

16.5.1 Modifying Instant Messaging and Presence Connections Details Using Fusion Middleware Control

To update connection details for an instant messaging and presence server:

1. Log in to Fusion Middleware Control and navigate to the home page for the WebCenter application. For more information, see:

   • Section 6.2, "Navigating to the Home Page for WebCenter Spaces"

   • Section 6.3, "Navigating to the Home Page for WebCenter Portal Applications"

2. Do one of the following:

   • For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.

   • For WebCenter Portal applications - From the Application Deployment menu, choose WebCenter > Service Configuration.

3. From the list of services on the WebCenter Service Configuration page, select Instant Messaging and Presence.

4. Select the connection name, and click Edit.

5. Edit connection details, as required. For detailed parameter information, see Table 16-2, "Instant Messaging and Presence Connection - Connection Details".

6. Click OK to save your changes.

7. To start using the updated (active) connection you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

16.5.2 Modifying Instant Messaging and Presence Connections Details Using WLST

Use the WLST command setIMPConnection to edit presence server connection details. For command syntax and examples, see the section, "setIMPConnection" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

If additional parameters are required to connect to your presence server, then use the setIMPConnectionProperty command. For more information, see the section, "setIMPConnectionProperty" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

16.6.1 Deleting Instant Messaging and Presence Connections Using Fusion Middleware Control

To delete an instant messaging and presence server connection:

1. Log in to Fusion Middleware Control and navigate to the home page for the WebCenter application. For more information, see:

   • Section 6.2, "Navigating to the Home Page for WebCenter Spaces"

   • Section 6.3, "Navigating to the Home Page for WebCenter Portal Applications"

2. Do one of the following:

   • For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.

   • For WebCenter Portal applications - From the Application Deployment menu, choose WebCenter > Service Configuration.

3. From the list of services on the WebCenter Service Configuration page, select Instant Messaging and Presence.

4. Select the connection name, and click Delete.

5. To effect this change you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

   Note:

   Before restarting the managed server, mark another connection as active; otherwise, the service is disabled.

16.6.2 Deleting Instant Messaging and Presence Connections Using WLST

Use the WLST command deleteConnection to remove a presence server connection. For command syntax and examples, see the section, "deleteConnection" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."