7 Integrating Oracle WebCenter Discussions

This chapter explains how you can embed discussion forums in your WebCenter applications. The discussion forum is a powerful service that enables users to share information and discuss topics embedded within your WebCenter application.

Introduction to Oracle WebCenter Discussions
Integrating Oracle WebCenter Discussions

7.1 Introduction to Oracle WebCenter Discussions

One of the services that you can integrate into your WebCenter application is discussion forums. Users can browse threads in a convenient portlet to locate pertinent messages, and then go to the discussion forum to read more and add their own posts or replies. In particular, Oracle WebCenter Discussions provides you a J2EE application with an open architecture and extensive features. You can easily integrate Oracle WebCenter Discussions into your WebCenter application.

7.2 Integrating Oracle WebCenter Discussions

This section describes the following:

Section 7.2.1, "How to Install and Configure Oracle WebCenter Discussions"
Section 7.2.3, "How to Consume the Discussion Forum Portlet in Your WebCenter Application"

7.2.1 How to Install and Configure Oracle WebCenter Discussions

To install the Oracle WebCenter Discussions J2EE application, do the following:

Unzip jive_forums_silver_5_1_0.zip from the companion CD. Follow the installation instructions located in:

Note:
owc_discussions is the name of the directory in which you chose to unzip jive_forums_silver_5_1_0.zip.
```
owc_discussions\jive_forums_silver_5_1_0\documentation\install-guide.html
```
When you reach the point in the Oracle WebCenter Discussions installation instructions where you must install the jiveforums.war file in an application server, you need to deploy the WAR file through Oracle Enterprise Manager 10g as described in the steps that follow.
Log in to the Application Server Control as an administrator.
Click the Oracle Application Server instance to go to its application server page.
We recommend you create a new OC4J instance to contain Oracle WebCenter Discussions. Although not recommended, you can use an existing OC4J instance. To create a new OC4J instance, click Create OC4J Instance (Figure 7-1).

Figure 7-1 Oracle Application Server Instance

Description of "Figure 7-1 Oracle Application Server Instance"
Fill in the values for the new OC4J instance (Figure 7-2). Be sure to check Start this OC4J instance after creation.

Figure 7-2 Create OC4J Instance

Description of "Figure 7-2 Create OC4J Instance"
Click Create. Your instance should now appear in the list of System Components (Figure 7-3).

Figure 7-3 Application Server Page of Application Server Control

Description of "Figure 7-3 Application Server Page of Application Server Control"
Follow the instructions in Section 18.3, "Configuring Your Application Server or Standalone OC4J to Run Portlets" to configure your OC4J instance to run portlets.
Click the name of the OC4J instance. The Home tab of the instance appears (Figure 7-4).

Figure 7-4 Home Tab for OC4J Instance

Description of "Figure 7-4 Home Tab for OC4J Instance"
Click the Applications tab (Figure 7-5).

Figure 7-5 Applications Tab for OC4J Instance

Description of "Figure 7-5 Applications Tab for OC4J Instance"
Click Deploy.
Choose the location of the WAR file (local or host) and specify the path (Figure 7-6). From the companion CD, the path is:
```
owc_discussions\jive_forums_silver_5_1_0\jiveforums.war
```
Choose Automatically create a new deployment plan (Figure 7-6).

Figure 7-6 Deploy: Select Archive Page

Description of "Figure 7-6 Deploy: Select Archive Page"
Click Next. Note that, if the WAR file is local, it may take several minutes to upload to the server.
Enter Application Name (for example, owc_discussions). Ensure also that the Context Root is something meaningful (for example, owc_discussions) because you will use this context root to call your Wiki application from this point forward (Figure 7-7).

Figure 7-7 Deploy: Application Attributes Page

Description of "Figure 7-7 Deploy: Application Attributes Page"
Click Next.
The Deployment Settings page appears (Figure 7-8). Click the Go to Task icon for Configure Class Loading.

Figure 7-8 Deploy: Deployment Settings Page

Description of "Figure 7-8 Deploy: Deployment Settings Page"
From the Configure Class Loading page, go to the Configure Web Module Class Loaders section (Figure 7-9) and check Search Local Classes First for the Jive Forums 5 Web module.

Figure 7-9 Configure Web Module Class Loaders Section

Description of "Figure 7-9 Configure Web Module Class Loaders Section"
Click OK. Note the informational message at the top of the page that indicates that the deployment plan was successfully updated.
Click Deploy.
Once the deployment has completed successfully, you get a confirmation message (Figure 7-10). If the deployment is not successful, review the log and confirm that you had the correct deployment settings.

Figure 7-10 Confirmation of Deployment

Description of "Figure 7-10 Confirmation of Deployment"
Click Return. You should now see the application running in your OC4J instance (Figure 7-11).

Note:
If you do not intend to use the discussion forum portlets, restart the OC4J instance now.

Figure 7-11 Applications Tab with Oracle WebCenter Discussions Application Deployed

Description of "Figure 7-11 Applications Tab with Oracle WebCenter Discussions Application Deployed"
Return to the Oracle WebCenter Discussions installation instructions in owc_discussions\jive_forums_silver_5_1_0\documentation\install-guide.html and follow the remainder of the steps. Under the User, Group, and Authentication Systems configuration, the LDAP credential store is not supported. The recommended option is the default user management. Therefore, when you go through the setup tool, choose the default option when prompted to Choose a user, group and authentication system. This default setup is overridden when you perform the steps in Section 7.2.2, "How to Configure Java SSO with Your Oracle WebCenter Discussions Application and Portlet".
To confirm that you have successfully set up Oracle WebCenter Discussions, go to the Admin Console and attempt to login as the administrator you created during the installation process:
```
http://host:port/owc_discussions/admin/
```
If you are able to successfully login to the Admin Console, you can proceed to Section 7.2.2, "How to Configure Java SSO with Your Oracle WebCenter Discussions Application and Portlet" and perform the steps to integrate Oracle WebCenter Discussions and the discussion forum portlet with Java SSO.

7.2.2 How to Configure Java SSO with Your Oracle WebCenter Discussions Application and Portlet

To integrate the discussion forum portlet and Oracle WebCenter Discussions Web application in your WebCenter application, you must perform the steps in this section after you have successfully deployed and configured the Oracle WebCenter Discussions Web application.

These steps describe how to properly configure security for Oracle WebCenter Discussions. The Java SSO integration requires custom classes to override the standard AuthFactory and UserManager classes. In OracleSSOAuthFactory and OracleSSOUserManager, Oracle ADF APIs check user authentication and user manager. In addition, you must override a few action classes for user login/logout, and filter classes for presence and administration. Finally, to integrate the ADF authentication servlet for Java SSO login, you need to change the web.xml and orion-application.xml.

To integrate your discussion forum portlet and the Oracle WebCenter Discussions application, perform the following steps:

To enable single sign-on between the Oracle WebCenter Discussions application and the discussion forum portlet, you use Java SSO to authenticate users from a central user data store. You must synchronize an Oracle WebCenter Discussions user and the Oracle Application Server administrator user. When using the JAZN authentication model, you create an oc4jadmin user in the Oracle WebCenter Discussions administration interface and assign it administrative privileges as follows:

Note:
It is mandatory that you create the oc4jadmin user at this point. Otherwise, you will not be able to log in to the Oracle WebCenter Discussions application later.
1. Open the Oracle WebCenter Discussions administration interface by going to the following URL:
```
http://host:port/owc_discussions/admin/
```
2. Login using the administrator user name and password you created during the installation of Oracle WebCenter Discussions. The Oracle WebCenter Discussions Admin Console appears as shown in Figure 7-12.
  
  Figure 7-12 Oracle WebCenter Discussions Admin Console
  
  Description of "Figure 7-12 Oracle WebCenter Discussions Admin Console"
3. Click the Users/Groups tab (Figure 7-13).
  
  Figure 7-13 User/Groups Tab of Admin Console
  
  Description of "Figure 7-13 User/Groups Tab of Admin Console"
4. Click Create User from the left pane.
5. Specify oc4jadmin for Username and fill in the other required properties (Figure 7-14).
  
  Figure 7-14 Create User Page
  
  Description of "Figure 7-14 Create User Page"
6. Click Create User.
7. Once the oc4jadmin user is created, you need to grant it administrator privileges. Click the Settings tab (Figure 7-15).
  
  Figure 7-15 Settings Tab of the Admin Console
  
  Description of "Figure 7-15 Settings Tab of the Admin Console"
8. Click Grant New Permissions.
9. For Choose the permission(s), select System Admin (Figure 7-16).
10. For Choose a user or group to grant the permission(s) to, select A Specific User and enter oc4jadmin in the adjoining field (Figure 7-16).
  
  Figure 7-16 Grant New Permissions
  
  Description of "Figure 7-16 Grant New Permissions"
11. Click Grant New Permission.
Click the System tab. You need to change the default classes for AuthFactory and UserManager by adding two new properties.
Click System Properties (Figure 7-17) and scroll to the bottom of the page, where you should see the Add new property section.

Figure 7-17 System Properties of System Tab

Description of "Figure 7-17 System Properties of System Tab"
For Property Name, enter AuthFactory.className.
For Property Value, enter:
```
oracle.jive.sso.OracleSSOAuthFactory
```
Click Save Property (Figure 7-18).

Figure 7-18 Add new property Section

Description of "Figure 7-18 Add new property Section"
Repeat the previous three steps using UserManager.className as the Property Name and the following as the Property Value:
```
oracle.jive.sso.OracleSSOUserManager
```
This class extends the Oracle WebCenter Discussions DbUserManager.
To complete the portlet setup process, you now must modify some configuration files. The recommended method of making these modifications is to run deploy-jive-portlet.jar, which can be found on the companion CD. deploy-jive-portlet.jar configures web.xml, xwork-community.xml (in jiveforums-5.1.0.jar), orion-application.xml, and jive_startup.xml, and it unzips oracle-jive-portlet.zip. We recommend the use of deploy-jive-portlet.jar because it reduces the risk of manual errors, such as typos, in the configuration files. It also automatically backs up the previous versions of your configurations files, which can be useful if you later undeploy the portlet and return to your previous configuration

Alternatively, if for any reason you want to perform this process manually, you can follow the steps in Section 7.2.2.2, "Manual Configuration Steps for Portlet Deployment".

To run deploy-jive-portlet.jar, perform the following steps:
1. Copy deploy-jive-portlet.jar and oracle-jive-portlet.zip from the companion CD to:
```
j2ee/OC4J_instance/applications/owc_discussions/jiveforums
```
2. Ensure that you have JDK 1.5 in your PATH variable. If not, you can set PATH to point to the JDK 1.5 found in ORACLE_HOME/jdk/bin, where ORACLE_HOME is the Oracle WebCenter home.
3. From Enterprise Manager, stop the OC4J instance that runs your Oracle WebCenter Discussions application.
4. Run the following command line:
```
java -client -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80
 -jar deploy-jive-portlet.jar
```
  Note:
  If you are running through a proxy, you need to specify values for http.proxyHost and http.proxyPort on the command line as well.
  
  If you need to undeploy for some reason, you can run the following command line:
```
java -client -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80
 -jar deploy-jive-portlet.jar undeploy
```
5. When you run the command line, the tool prompts you for the full path to your jiveHome directory. Enter the path that you used when you set up the jiveHome directory according to the instructions in:
```
owc_discussions\jive_forums_silver_5_1_0\documentation\install-guide.html
```

Delete the following directory:

j2ee/OC4J_instance/application-deployment/owc_discussions/

Go back to Enterprise Manager and start the OC4J instance. Java SSO should appear as an application under the OC4J instance. Once the instance is started, confirm that Java SSO is running. If Java SSO is down, then start it.

When you start Java SSO, you might get a warning message (Figure 7-19) that Java SSO is not properly configured. This warning indicates that you are running multiple Java SSO applications in a cluster. To ensure that you properly configure Java SSO for a clustered environment, refer to Section 7.2.2.1.1, "Clustered Configurations for Java SSO"

Figure 7-19 Warning for Java SSO Configuration

Description of "Figure 7-19 Warning for Java SSO Configuration"
Upon successful completion of these steps, your Oracle WebCenter Discussions software and the sample portlet are installed and ready for use.
To create new users and start working with discussion forums, you need to create users in your underlying security model. In this case, we used the Java SSO model. For information on Java SSO security and how to create users, refer to Oracle Containers for J2EE Security Guide. If you are using file-based security, refer to Section 7.2.2.1.3, "File-Based Security" for configuration tips.

When you log in with a new user in Java SSO, it creates the same user in the Oracle WebCenter Discussions user management with normal user privileges. To grant this user administrator privileges, perform the following steps:

Note:
The steps that follow are similar to the ones you performed on the oc4jadmin user earlier in this procedure.
1. Open the Oracle WebCenter Discussions administration interface by going to the following URL:
```
http://host:port/owc_discussions/admin/
```
2. Login using the administrator user name and password you created during the installation of Oracle WebCenter Discussions. The Oracle WebCenter Discussions Admin Console appears.
3. From the Admin Console, click the Settings tab.
4. Click Grant New Permissions.
5. For Choose the permission(s), select System Admin.
6. For Choose a user or group to grant the permission(s) to, select A Specific User and enter the name of the user in the adjoining field.
7. Click Grant New Permission.
You can also use the Admin Console to create and manage categories, forums, users and groups. Refer to the Jive Forums Administrator's Guide (forums-admin-guide.pdf) on the companion CD for more information.
For more information on consuming the discussion forum portlet in your WebCenter application, refer to Section 7.2.3, "How to Consume the Discussion Forum Portlet in Your WebCenter Application".

7.2.2.1 Configuration Tips

This section provides configuration tips for your Oracle WebCenter Discussions application and portlet:

Clustered Configurations for Java SSO
Database Dependency
File-Based Security

7.2.2.1.1 Clustered Configurations for Java SSO

You can set custom.sso.key.alias from Enterprise Manager. Click Java SSO Configuration at the bottom of the Cluster Topology page for your application server instance. Refer to the OC4J Java Single Sign-On chapter in the Oracle Containers for J2EE Security Guide.

When you configure Java SSO from Enterprise Manager, users may encounter an error where the Oracle Application Server home page displays when they try to logout. To correct this problem, delete the following properties from jazn.xml:

property name="custom.sso.cookie.domain" value=""
property name="custom.sso.url.param" value=""

7.2.2.1.2 Database Dependency

You cannot change the underlying database of Oracle WebCenter Discussions. If you try to redeploy the Oracle WebCenter Discussions application to a new database, it will not function correctly because it relies on some customized features of the original Oracle WebCenter Discussions database.

7.2.2.1.3 File-Based Security

In general, we recommend that you use LDAP for your user data store. In cases where you must use file-based security, you should be aware of the following issue:

When configuring the file-based security provider for a clustered OC4J, JAZN does not pick up the configured system-jazn-data.xml file. Therefore, when you create a new user from Enterprise Manager, it is only added in j2ee/home/config/system-jazn-data.xml and is not available in the other, clustered OC4J instances.

To resolve this issue, you must manually copy and paste the user and role from j2ee/home/config/system-jazn-data.xml to the clustered OC4J_HOME/config/system-jazn-data.xml.

7.2.2.2 Manual Configuration Steps for Portlet Deployment

As an alternative to running deploy-jive-portlet.jar, you can manually perform the following steps:

Extract xwork-community.xml from ORACLE_HOME/j2ee/OC4J_instance/applications/owc_discussions/owcd_root_context/WEB-INF/lib/jiveforums-5.1.0.jar. To extract the file, run the following command:
```
jar xvf jiveforums-5.1.0.jar xwork-community.xml
```
Note:
For the jar commands in these steps, we recommend using the jar executable located in ORACLE_HOME/jdk/bin.
Open xwork-community.xml in a text editor and modify all of the login/logout actions between the  and  tags to use the classes available in the jsso-action-classes.xml file located in the following directory:
```
ORACLE_HOME/j2ee/OC4J_instance/applications/owc_discussions/owcd_root_context/
WEB-INF
```
After making the changes, save the file and run the following command to copy it back into the JAR file:
```
jar uvf jiveforums-5.1.0.jar xwork-community.xml
```
Log in to the Application Server Control as an administrator.
Click the Oracle Application Server instance to go to its application server page.
Click the OC4J instance where you are running the Oracle WebCenter Discussions application.
Click Stop.
Make a backup of the web.xml and /WEB-INF/lib/jiveforums-5.1.0.jar files from the following directory:
```
ORACLE_HOME/j2ee/OC4J_instance/applications/owc_discussions/owcd_root_context
```
The portlet is available in the oracle-jive-portlet.zip file on the companion CD. Unzip the files into:
```
ORACLE_HOME/j2ee/OC4J_instance/applications/owc_discussions/owcd_root_context
```
To configure the discussion forum portlet with the Oracle WebCenter Discussions application, you need to modify the web.xml file in ORACLE_HOME/j2ee/OC4J_instance/applications/owc_discussions/owcd_root_context/WEB-INF as follows:
1. Change the XML header to look like the following:
```
<?xml version = '1.0' encoding = 'UTF-8' standalone = 'yes'?>
```
2. Open the file called jive-portlet-for-web.xml located in ORACLE_HOME/j2ee/OC4J_instance/applications/owc_discussions/owcd_root_context/WEB-INF.
3. Select all of the content of the file and copy and paste it into web.xml, right after the <web-app> tag. This changes alters the security model and makes some role changes. Note that the security role and authentication constraints can be changed to be synchronized with roles and users added from the Enterprise Manager console.
4. Modify the AdminActionFilter and PresenceFilter in the web.xml file as shown in Example 7-1 to override the Java SSO integration. If these filters are not already present, you need to create them.
  Example 7-1 web.xml Filter Modifications
```
<filter>
 <filter-name>AdminActionFilter</filter-name>
  <filter-class>
   oracle.jive.sso.actions.SSOAdminActionFilter
  </filter-class>
</filter>
<filter> <filter-name>PresenceFilter</filter-name>
  <filter-class>
   oracle.jive.sso.actions.SSOPresenceFilter
  </filter-class>
</filter>
```
You must now modify the orion-application.xml file to point to the correct JAZN provider. If you have not previously modified the orion-application.xml located in ORACLE_HOME/j2ee/OC4J_instance/applications/owc_discussions/owcd_root_context/META-INF, you can simply replace it with the orion-application.xml.default file located in the same directory.

If you have previously made changes to orion-application.xml that you need to preserve, then you can edit the file to add or replace the JAZN provider to look similar to the following:
```
<library path="./adf"></library>
<jazn provider="XML" default-realm="jazn.com">
  <jazn-web-app auth-method="CUSTOM_AUTH"/>
</jazn>
```

To clear any cached copies, delete the following directory:

ORACLE_HOME/j2ee/OC4J_instance/applications/owc_discussions/jiveforums/j2ee/
home/applications-deployments/jive_directory

Set admin.tryAlternativeLogin in jiveHome/jive_startup.xml by adding the following lines somewhere before the </jive> tag:
```
<admin>
  <tryAlternativeLogin>true</tryAlternativeLogin>
</admin>
```
Return to step 10 in Section 7.2.2, "How to Configure Java SSO with Your Oracle WebCenter Discussions Application and Portlet" and complete the remainder of the procedure

7.2.3 How to Consume the Discussion Forum Portlet in Your WebCenter Application

To consume the discussion forum portlet in your WebCenter application, do the following:

Start Oracle JDeveloper and create a new WebCenter application or open an existing one.
Register your producer according to the instructions in Section 4.3.1.1, "Registering WSRP Portlet Producers". Your URL Endpoint should be of the following form:
```
http://host:port/owc_discussions/portlets/wsrp2?WSDL
```
Your producer should then be available for consumption from the Component Palette.
Open a JSP or create a new one according to the information in Section 4.2, "Building WebCenter Application-Enabled Pages in Oracle JDeveloper with Oracle ADF". Note that for the discussion forum portlet to work, you must choose Automatically Expose UI Components in a New Managed Bean on the Component Binding page of the Create JSF JSP wizard.

For information about the security configuration of the application consuming the discussion forum portlet, refer to Section 7.2.3.1, "Configuring Security for the Portlet and Oracle WebCenter Discussions Application".
Drag and drop the JiveSamplePortlet onto your page. Refer to Section 4.3.2, "Adding Portlets to a Page" for more information on this procedure.

Once your portlet is on the page, you need to contextually link the portlet to the page using the data in Table 7-1 and Table 7-2. Refer to Section 4.5.1, "Linking Portlets to Pages" for the complete linking procedure.

Table 7-1 Page Parameter Names and Values

Parameter ID	Parameter Value
page_view	The name of any available view in the portlet, for example, `category_view`.
containerID	The corresponding containerID for the specified `page_view` value. For example, you would use the parent category id (1) for category and forum, parent forum id for thread, and parent thread id for messages. Refer to the Jive Forums documentation for more information.

Table 7-2 Page Variable Default Values

Page Variable	Default Value
JivePortlet1_1_page_view	${(bindings.page_view == null \|\| bindings.page_view == '') ? 'category_view' : bindings.page_view}
JivePortlet1_1_containerId	${(bindings.containerId== null \|\| bindings.containerId== '') ? '1' : bindings.containerId}

Page Variable

Default Value

JivePortlet1_1_page_view

${(bindings.page_view == null || bindings.page_view == '') ? 'category_view' : bindings.page_view}

JivePortlet1_1_containerId

${(bindings.containerId== null || bindings.containerId== '') ? '1' : bindings.containerId}

Run the page to confirm that the portlet appears as expected.

7.2.3.1 Configuring Security for the Portlet and Oracle WebCenter Discussions Application

You can optionally configure the application consuming the discussion forum portlet to use Oracle ADF security to authenticate users with Java SSO. By configuring security this way, the same authentication token is used to navigate from portlet links to Oracle WebCenter Discussions application and users only need to login once.

To configure Oracle ADF security for your consumer application, perform the steps described in Section 10.2.2, "Configuring Security for Your Application".