13 Integrating the Discussions Service

This chapter explains how to integrate the Discussions service in a custom WebCenter application.

This chapter includes the following sections:

• Section 13.1, "Introduction to Discussions"

• Section 13.2, "Basic Configuration for the Discussions Service"

• Section 13.3, "Advanced Information for the Discussions Service"

13.1 Introduction to Discussions

The Discussions service lets you expose discussion forums on your application pages. Users can use the Discussions service to create forums, post questions, and search for answers.

For information about the Discussions taxonomy with categories, forums, topics, and messages, see Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

13.1.1 Understanding the Discussions Service

With the Discussions service, you can do the following (according to your permissions):

• Create a new discussion forum or a new topic.

• Navigate into a forum from a list of available forums.

• Edit an existing discussion forum, topic, or message by clicking the Edit icon.

• Delete a forum, topic, or message by clicking the Delete icon.

• Reply to an existing topic or message by clicking the Reply icon.

• View the number of replies for a topic on the main forum view.

• Drill into a topic to read all replies by clicking the topic name.

• Add a watch to a topic or forum by clicking the Watch icon.

• View the following in the sidebar:

  • Watched topics

  • Watched forums

  • Most popular topics

  • Most recent topics

The Discussions service is integrated with many WebCenter Web 2.0 services, such as Instant Messaging and Presence, RSS, and Search (to search within forums) services. Use the Mail service to archive mails into discussions as threads. Use the Links service to link to a discussion from any WebCenter object, or, link to a WebCenter object.

Note: In a secured custom WebCenter application, Discussions permissions are allotted according to an individual user's assigned user role. A user can be a moderator, participant, or viewer. Some activities require moderator or participant roles. For more information, see Section 13.2.3, "Setting Security for Discussions."

Figure 13-1 shows a sample discussion forum topic list.

Figure 13-1 Discussion Forum Topics List

Description of "Figure 13-1 Discussion Forum Topics List"

For more information about the service at runtime, see Oracle Fusion Middleware User's Guide for Oracle WebCenter.

Note: You can see the Discussions service in action in the sample application, as described in Chapter 2, "Introduction to the WebCenter Sample Application."

13.1.2 Requirements for Discussions

The Discussions service requires a discussions server. Install and configure the discussions server that comes with Oracle Fusion Middleware.

For information on installing the Discussions server that comes with Oracle Fusion Middleware, see Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

13.2 Basic Configuration for the Discussions Service

This section describes required steps for adding the Discussions service to your application. It contains the following subsections:

• Section 13.2.1, "Setting up Connections for Discussions"

• Section 13.2.2, "Adding the Discussions Service at Design Time"

• Section 13.2.3, "Setting Security for Discussions"

13.2.1 Setting up Connections for Discussions

You must create a connection to the discussions server in your custom WebCenter application.

The Discussions service requires a WebCenter Discussion connection to the discussions server. When you create a WebCenter Discussion connection or set a connection as active, both the Announcements and Discussions services will use this same connection. If you already have an existing connection, then you can skip this section and see Section 13.2.2, "Adding the Discussions Service at Design Time."

If you do not have an existing connection, then you must create a new WebCenter Discussion connection.

13.2.1.1 Discussions Connections

The Discussions service requires a WebCenter Discussion connection to the discussions server.

Note: While you can set up the connections to back-end servers at design time in Oracle JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

13.2.1.2 How to Set Up Connections for Discussions

Follow these steps to set up the discussions connection.

1. Follow the steps in Chapter 3, "Implementing Security in Your Application."

2. In Oracle JDeveloper, open the application in which you plan to consume discussion forums.

   
   

   Note: If you already created a WebCenter Discussion connection for the Announcements service, then that will be used by default for the Discussions service. No extra configuration is required. However, if you want to use different WebCenter Discussion connection for the Announcements service and the Discussions service, then a manual entry in adf-config.xml is required.

   
   

3. In the Resource Palette, click the New icon and select New Connection, WebCenter Discussion Connection.

4. On the Name page, select to create the connection in Application Resources. (A connection in Application Resources will be available only for that application, while a connection in IDE Connections will be available for all applications you create. If you plan to use the connection in other applications, then select IDE Connections so you do not need to re-create it.)

5. For Connection Name, enter a unique name; for example, MyDiscussions.

6. Select the Set the default connection checkbox. You can have more than one connection, but only one can be active (default). If you have different discussions servers (for example, for each page in a space), then do not select the checkbox, but the service requires that one connection be marked as the default connection (Figure 13-2).

   
   

   Note: After you create a connection as the default connection, you cannot edit it so that it is not the default. To use a different default connection, you must create a new connection and mark that as the default connection.

   
   

   Figure 13-2 Create Discussion Connections, Step 1

   
   Description of "Figure 13-2 Create Discussion Connections, Step 1"
   
   

7. Click Next.

8. On the General page, enter values for the required parameters:

   • forum.url: The URL for your discussions server instance. For example: http://discuss-server.com:8888/owc_discussions.

   • admin.user: The user name of your discussions server (Jive) administrator; for example, admin. This account is used by the Discussions and Announcement services to perform administrative operations on behalf of WebCenter users.

9. Optionally, enter values for the other parameters:

   • connection.time.out: The time (in seconds) the service should wait for the server to respond while making the connection. If the discussions server does not respond in the given time, then it will abort the connection and report an error.

   • forum.connection.secure: Indicates whether a secure communication is required between the custom WebCenter application and the discussions server. The default value is false. When set to true (secured mode), all Web Services calls from the custom WebCenter application are sent with a user name token and client certificate.

   Figure 13-3 Create Discussions Connection, Step 2

   
   Description of "Figure 13-3 Create Discussions Connection, Step 2"
   
   

   For more information about options for securing your custom WebCenter application, see Section 24, "Securing Your WebCenter Application."

10. Click Test Connection, and if it is successful, then click Next.

11. On the Create Discussion Connection - Step 3 of 3 page, you can enable client-side WS-Security (Figure 13-4).

    First obtain the client-side certificate and store it in a local directory. Then click the Add Secured Property button to add each of the following additional parameters in your WebCenter Discussion connection to secure WS-Service calls:

    • keystore.location: The certificate file path in your local directory

      
      

      Note: If the application is deployed to WebLogic Server, then this path should be accessible on the deployed server. Make sure that the path is available to the application on the deployed server.

      
      

    • keystore.password: The keystore password.

    • keystore.type: The keystore type associated with the certificate. Valid values are: jks (Java Key Store) and pks.

    • encryption.key.alias: The key alias to be used for encryption.

    • encryption.key.password: The password for accessing the encryption key.

    Make sure your property key and value are the same as in the certificate.

    
    

    Note: If values should be secured, then add them with the Add Secured Property button.

    
    

    Figure 13-4 Create Discussions Connection, Step 3

    
    Description of "Figure 13-4 Create Discussions Connection, Step 3"
    
    

12. Click Finish. Your connection should now appear as a node under Application Resources - Connections.

13.2.2 Adding the Discussions Service at Design Time

This section explains a basic incorporation of the Discussions service.

13.2.2.1 Discussions Task Flows

The Discussions service provides several task flows (Table 13-1) to enable you to include the service in a form that best suits your needs.

Table 13-1 Discussions Service Task Flows

Task Flow	Description
Discussion Forums	This task flow displays the Oracle WebCenter Discussions Manager View, which allows the user to see all the discussions and their respective replies. It also allows users to perform various operations based on their privileges. A Moderator can perform create, read, update, and delete operations on all objects. A Participant can create a topic, edit a topic that has been created by him, and reply to a topic. A Viewer can only view objects. The parameters alter the way the view appears. For more information, see Section 13.3.1, "Customizing Discussions Views."
Discussions - Popular Topics	This task flow provides a view that allows users to see all the popular topics under a given category ID or forum ID. For more information, see Section 13.3.2, "Adding the Discussions - Popular Topics Task Flow."
Discussions - Recent Topics	This task flow displays a view that allows users to see all the recent topics given a category ID or forum ID. For more information, see Section 13.3.3, "Adding the Discussions - Recent Topics Task Flow."
Discussions - Watched Forums	This task flow displays a view that allows users to see all of their watched forums under a given category ID. For more information, see Section 13.3.4, "Adding the Discussions - Watched Forums Task Flow."
Discussions - Watched Topics	This task flow displays a view that allows users to see all their watched topics under a given category ID or forum ID. For more information, see Section 13.3.5, "Adding the Discussions - Watched Topics Task Flow."
Discussions - Sidebar View	This task flow displays a combined view of the Popular Topics, Recent Topics, Watched Topics, and Watched Forums task flows. Instead of adding four separate task flows, this single task flow presents all four views with a drop-down list so that end users can personalize it For more information, see Section 13.3.6, "Adding the Discussions - Sidebar View Task Flow."

13.2.2.2 How to Add Discussions to your Application

The Discussion Forums task flow provides a complete view of your discussions. To add the Discussion Forums task flow to your WebCenter application, follow these steps.

1. Follow the steps described in Section 11.1.1, "How to Prepare Your Application to Consume Services" to implement security and create a new customizable page in your application.

2. Open the page on which you want to add the Discussions service.

3. In the Resource Palette, expand My Catalogs, WebCenter Services Catalog, and Task Flows.

4. Drag Discussions from the Resource Palette and drop it onto the page.

5. When prompted, select Region as the way to create the task flow.

6. You may be prompted to add the discussions library to your project. If so, then click Add Library. This operation may take a moment to complete.

7. In the Edit Task Flow Binding dialog box, enter values for the parameters. Table 13-2 describes the parameters.

   
   

   Note: The parameters alter the way the view appears. For more information, see Section 13.3.1, "Customizing Discussions Views."

   
   

   Table 13-2 Parameters for Discussion Forums Task Flow

   Parameters	Description
   categoryId	This optional parameter is an identifier for an existing category in your Oracle WebCenter Discussions instance to which the view should be scoped. When no value is supplied, it defaults to the appropriate root category of the discussions server. (This root category ID can be overridden by supplying an additional property named application.root.category.id in the connection.) For testing purposes, you may want to create a new category through the Oracle WebCenter Discussions administrator interface and then reference that category identifier here.
   forumId	This parameter is an identifier for an existing forum that resides inside the given categoryId. It is optional. You should be certain about the specific forum for which you want to see data before entering this value.
   isCategoryView	A means of showing the forums grouped under the Category ID category or the topics specified under the Forum ID forum. True means you want the task flow to display the forums classified under Category ID; false, the default value, means you want the task flow to display the topics associated with the specified Forum ID. This parameter value works in combination with other parameters.
   showRecursiveForums	This parameter determines if you show forums either in a category only or in subcategories. True means all forums under a given category/subcategory are shown; false means only the category's direct child forums are shown. The default value is false. Note: A value of true can impact performance.

   
   

8. Click OK.

   
   

   Note: If you created a connection in IDE and not in the application, then the connection must be added to the application. For example, in the Resource Palette under IDE Connections, right-click the connection and select Add to Application.

   
   

9. Save and run your page.

   
   

   Note: All instances of the Discussion Forums task flow in an application run against the same discussions server: it is unnecessary to add more than one Discussion Forums task flow instance. This is true for all service task flows that require connections to back-end servers, such as task flows from the Announcements or Mail services.

   
   

The Discussion Forums main view contains some features that require other services in your application.

• For the links in the main view to work, you must have configured the Links service. For more information, see Chapter 16, "Integrating the Links Service."

• For users' presence indicators to work, you must have configured the Oracle WebCenter Presence service. For more information, see Chapter 15, "Integrating the Instant Messaging and Presence Service."

• Oracle recommends that the discussions server and WebCenter point to the same identity store. If the custom WebCenter application and the discussions page are configured to be secure, then upon logging in to the application, then the Discussions service respects those credentials in the discussions server.

13.2.3 Setting Security for Discussions

In a non-secured custom WebCenter application, identity propagation cannot happen. A user will be a guest (or anonymous) user who can view only public categories and forums.

In an ADF-secured custom WebCenter application, identity propagation is enabled. Based on the identity, appropriate permissions are matched and corresponding actions are enabled.

The user name that you use to log in to the application will be used to log in to the discussions server. The recommended approach is to have the discussions server and the custom WebCenter application point to the same identity store. When you run the page, you are presented with a login page for user credentials. Enter the credentials with the required privileges in the discussions server.

Note: The Discussions services requires that the identity store be LDAP-based; that is, not file-based with jazn-data.xml.

For information about configuring ADF security, see Section 3.5, "Implementing Security in Your Application."

13.3 Advanced Information for the Discussions Service

This section describes optional features available with this service.

13.3.1 Customizing Discussions Views

You can customize the look and feel of Discussion Forums views by changing parameter values. The following combinations are possible:

Note: A bidirectional link connects back and forth. For example, when you create a link from a discussion topic to a document, a link from the document back to the topic also is created. Similarly, when you delete the link from the discussion topic to a document, the link from the document back to the topic automatically is deleted.

• categoryId: This displays the forums list view if there is more than one forum. If there is only one forum, then it will drill into the forum and list all topics with a bidirectional link enabled.

• categoryId and forumId: This displays the topics list view with a bidirectional link enabled.

• isCategoryView is set to true: This displays the topics list view with a bidirectional link enabled.

• categoryId and forumId and isCategoryView is set to false: This displays the topics list view, but a bidirectional link is not enabled.

• categoryId and isCategoryView is set to true: This displays the forums list view if there is more than one forum. If there is only one forum, then it displays that forum with a bidirectional link enabled.

• forumId and isCategoryView is set to false: This displays the topics list view, but a bidirectional link is not enabled.

• categoryId and isCategoryView is set to false: This is similar to when categoryId alone is given.

• forumId and isCategoryView is set to true: This is similar to when forumId and isCategoryView is set to false.

• isCategoryView = true or false: This is ignored. It goes with the default scope in a custom WebCenter application.

• forumId: This is similar to forumId and isCategoryView is set to false.

Figure 13-5 shows the Discussion Forums view with the categoryId parameter set.

Figure 13-5 Discussions Forum View with categoryId Set

Description of "Figure 13-5 Discussions Forum View with categoryId Set"

With the categoryId parameter set, you can click any forum or any topic, as shown in Figure 13-6 and Figure 13-7.

Figure 13-6 Click any Forum in the Discussion Forums View

Description of "Figure 13-6 Click any Forum in the Discussion Forums View"

Figure 13-7 Click any Topic in the Discussion Forums View

Description of "Figure 13-7 Click any Topic in the Discussion Forums View"

Figure 13-8 shows the Discussion Forums view with the forumId parameter set.

Figure 13-8 Discussion Forums View with the forumId Parameter Set

Description of "Figure 13-8 Discussion Forums View with the forumId Parameter Set"

With the forumId parameter given, you can click any topic, as shown in Figure 13-9.

Figure 13-9 Click any Topic in the Discussion Forums View

Description of "Figure 13-9 Click any Topic in the Discussion Forums View"

13.3.2 Adding the Discussions - Popular Topics Task Flow

The Discussions - Popular Topics task flow provides a view that allows users to see all the popular topics under a given category ID or forum ID.

To add the Discussions - Popular Topics task flow to your custom WebCenter application, follow the same instructions that you did for the Discussion Forums task flow in Section 13.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Popular Topics onto the page.

Table 13-3 describes the available parameters for this task flow.

Table 13-3 Parameters for Discussions - Popular Topics Task Flow

Parameters	Description
categoryId	This optional parameter is an identifier for an existing category in your Oracle WebCenter Discussions instance to which the view should be scoped. When no value is supplied, it defaults to the appropriate root category of the discussions server. (This root category ID can be overridden by supplying an additional property named application.root.category.id in the connection.) For testing purposes, you may want to create a new category through the Oracle WebCenter Discussions administrator interface and then reference that category identifier here.
forumId	This parameter is an identifier for an existing forum in your Oracle WebCenter Discussions instance for which popular topics should be fetched. If both categoryId and forumId are given, then only categoryId is honored.
disableToolbar	This parameter indicates whether the toolbar, including the Refresh icon, should be displayed. It can be ${true}, ${false}, or undefined. If you leave this parameter undefined, then the default behavior (false) is to show the toolbar.

Figure 13-10 shows how the Discussions - Popular Topics task flow looks at runtime.

Figure 13-10 Discussions - Popular Topics View at Runtime

Description of "Figure 13-10 Discussions - Popular Topics View at Runtime"

13.3.3 Adding the Discussions - Recent Topics Task Flow

The Discussions - Recent Topics task flow displays a view that allows users to see all the recent topics given a category ID or forum ID.

To add the Discussions - Recent Topics task flow to your custom WebCenter application, follow the same instructions that you did for the Discussion Forums task flow in Section 13.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Recent Topics onto the page.

Table 13-4 describes the available parameters for this task flow.

Table 13-4 Parameters for Discussions - Recent Topics Task Flow

Parameters	Description
categoryId	This optional parameter is an identifier for an existing category in your Oracle WebCenter Discussions instance to which the view should be scoped. When no value is supplied, it defaults to the appropriate root category of the discussions server. (This root category ID can be overridden by supplying an additional property named application.root.category.id in the connection.) For testing purposes, you may want to create a new category through the Oracle WebCenter Discussions administrator interface and then reference that category identifier here.
forumId	This parameter is an identifier for an existing forum in your Oracle WebCenter Discussions instance for which popular topics should be fetched. If both categoryId and forumId are given, then only categoryId is honored.
disableToolbar	This parameter indicates whether the toolbar, including the Refresh icon, should be displayed. It can be ${true}, ${false}, or undefined. If you leave this parameter undefined, then the default behavior is to show the toolbar.

Figure 13-11 shows how the Discussions - Recent Topics task flow looks at runtime.

Figure 13-11 Discussions - Recent Topics View at Runtime

Description of "Figure 13-11 Discussions - Recent Topics View at Runtime"

13.3.4 Adding the Discussions - Watched Forums Task Flow

The Discussions - Watched Forums task flow displays a view that allows users to see all of their watched forums under a given category ID.

To add the Discussions - Watched Forums task flow to your custom WebCenter application, follow the same instructions that you did for the Discussion Forums task flow in Section 13.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Watched Forums onto the page.

Table 13-5 describes the available parameters for this task flow.

Table 13-5 Parameters for Discussions - Watched Forums Task Flow

Parameters	Description
categoryId	This optional parameter is an identifier for an existing category in your Oracle WebCenter Discussions instance to which the view should be scoped. When no value is supplied, it defaults to the appropriate root category of the discussions server. (This root category ID can be overridden by supplying an additional property named application.root.category.id in the connection.) For testing purposes, you may want to create a new category through the Oracle WebCenter Discussions administrator interface and then reference that category identifier here.
disableToolbar	This parameter indicates whether the toolbar, including the Refresh icon, should be displayed. It can be ${true}, ${false}, or undefined. If you leave this parameter undefined, then the default behavior is to show the toolbar.

Figure 13-12 shows how the Discussions - Watched Forums task flow looks at runtime.

Figure 13-12 Discussions - Watched Forums View at Runtime

Description of "Figure 13-12 Discussions - Watched Forums View at Runtime"

13.3.5 Adding the Discussions - Watched Topics Task Flow

The Discussions - Watched Topics task flow displays a view that allows users to see all their watched topics under a given category ID or forum ID.

To add the Discussions - Watched Topics task flow to your custom WebCenter application, follow the same instructions that you did for the Discussion Forums task flow in Section 13.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Watched Topics onto the page.

Table 13-6 describes the available parameters for this task flow.

Table 13-6 Parameters for Discussions - Watched Topics Task Flow

Parameters	Description
categoryId	This optional parameter is an identifier for an existing category in your Oracle WebCenter Discussions instance to which the view should be scoped. When no value is supplied, it defaults to the appropriate root category of the discussions server. (This root category ID can be overridden by supplying an additional property named application.root.category.id in the connection.) For testing purposes, you may want to create a new category through the Oracle WebCenter Discussions administrator interface and then reference that category identifier here.
forumId	This parameter is an identifier for an existing forum in your Oracle WebCenter Discussions instance for which watched topics should be fetched. If both categoryId and forumId are given, then only categoryId is honored.
disableToolbar	This parameter indicates whether the toolbar, including the Refresh icon, should be displayed. It can be ${true}, ${false}, or undefined. If you leave this parameter undefined, then the default behavior is to show the toolbar.

Figure 13-13 shows how the Discussions - Watched Topics task flow looks at runtime.

Figure 13-13 Discussions - Watched Topics View at Runtime

Description of "Figure 13-13 Discussions - Watched Topics View at Runtime"

13.3.6 Adding the Discussions - Sidebar View Task Flow

The Discussions - Sidebar View task flow displays a combined view of the Popular Topics, Recent Topics, Watched Topics, and Watched Forums task flows. Instead of adding four separate task flows, this single task flow presents all four views with a dropdown list so that end users can personalize it.

By default, Watched Topics are displayed. This task flow takes only one parameter: categoryId.

To add the Discussions - Sidebar View task flow to your custom WebCenter application, follow the same instructions that you did for the Discussion Forums task flow in Section 13.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Sidebar View onto the page.

Figure 13-14 shows how the Discussions - Sidebar View task flow looks at runtime.

Figure 13-14 Discussions - Sidebar View at Runtime

Description of "Figure 13-14 Discussions - Sidebar View at Runtime"

13.3.7 Using Custom Discussions APIs

Oracle WebCenter Discussions provides APIs, so you can further customize your application. To learn more about them, see the Jive Forums documentation on the WebCenter product page in the Fusion Middleware library.

13.3.8 Troubleshooting the Discussions Service

This section describes common problems and solutions for the Discussions service.

Problem

It can take several minutes to fetch data from recursive forums. For example, if you drop the Discussions task flow on the page with the categoryId and forumId parameters left blank and you set the showrecursive parameter to ${'true'}, then it could take several minutes to scroll through all the forums.

Solution

The option to show recursive forums is not recommended for performance reasons.

Problem

Users can log on to Oracle WebCenter but cannot log on to Oracle WebCenter Discussions.

Solution

Make sure that Oracle WebCenter Discussions is configured to use the same LDAP provider as the custom WebCenter application. Contact your administrator for details. For information about configuring LDAP, see the "Configuring the Discussions Server to Share the Identity Store LDAP" section in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

Problem

When you access a discussions forum from your custom WebCenter application, the following error message is displayed:

No default or active connection available for: Discussion Forum

Solution

Ensure the following:

• Ensure that you have created a WebCenter Discussion connection.

• Ensure the required WebCenter Discussion connection is marked as the default connection.

Problem

While performing certain operations on Discussions Manager task flows, you encounter error messages like "Forum not found" or "Topic not found."

Solution

Check the following:

• Ensure that the Oracle WebCenter Discussions server is up and running.

• Ensure the forum or topic exist on the discussions server.

• Ensure that you have the required privileges for the forum or topic that you are editing.

If all of these settings are fine and the problem persists, contact your administrator for details.