Oracle® WebCenter Framework Developer's Guide 10g (10.1.3.2.0) B31074-04 |
|
Previous |
Next |
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.
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.
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"
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
Fill in the values for the new OC4J instance (Figure 7-2). Be sure to check Start this OC4J instance after creation.
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
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).
Click the Applications tab (Figure 7-5).
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).
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
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
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
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.
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
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.
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 theoc4jadmin user at this point. Otherwise, you will not be able to log in to the Oracle WebCenter Discussions application later. |
Open the Oracle WebCenter Discussions administration interface by going to the following URL:
http://host:port/owc_discussions/admin/
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
Click the Users/Groups tab (Figure 7-13).
Figure 7-13 User/Groups Tab of Admin Console
Click Create User from the left pane.
Specify oc4jadmin
for Username and fill in the other required properties (Figure 7-14).
Click Create User.
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
Click Grant New Permissions.
For Choose the permission(s), select System Admin (Figure 7-16).
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).
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
For Property Name, enter AuthFactory.className
.
For Property Value, enter:
oracle.jive.sso.OracleSSOAuthFactory
Click Save Property (Figure 7-18).
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:
Copy deploy-jive-portlet.jar
and oracle-jive-portlet.zip
from the companion CD to:
j2ee/OC4J_instance/applications/owc_discussions/jiveforums
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.
From Enterprise Manager, stop the OC4J instance that runs your Oracle WebCenter Discussions application.
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 forhttp.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
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
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 theoc4jadmin user earlier in this procedure. |
Open the Oracle WebCenter Discussions administration interface by going to the following URL:
http://host:port/owc_discussions/admin/
Login using the administrator user name and password you created during the installation of Oracle WebCenter Discussions. The Oracle WebCenter Discussions Admin Console appears.
From the Admin Console, click the Settings tab.
Click Grant New Permissions.
For Choose the permission(s), select System Admin.
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.
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".
This section provides configuration tips for your Oracle WebCenter Discussions application and portlet:
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=""
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.
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
.
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 thejar 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 <!-- Base actions -->
and <!--Default skin -->
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:
Change the XML header to look like the following:
<?xml version = '1.0' encoding = 'UTF-8' standalone = 'yes'?>
Open the file called jive-portlet-for-web.xml
located in ORACLE_HOME
/j2ee/
OC4J_instance
/applications/owc_discussions/
owcd_root_context
/WEB-INF
.
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.
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
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, |
containerID |
The corresponding containerID for the specified |
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} |
Run the page to confirm that the portlet appears as expected.
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".