17 Integrating the Discussions Service

This chapter explains how to integrate the Discussions service in a custom WebCenter application at design time. For more information about managing and including discussions, see:

• "Managing the Announcements and Discussions Services" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter

• "Working with the Discussions Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter

This chapter includes the following sections:

• Section 17.1, "Introduction to Discussions"

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

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

17.1 Introduction to Discussions

The Discussions service lets you expose discussion forums on your application pages, so users can create forums, post questions, and search for answers. For example, customers can share product reviews, or a customer service department can answer questions online. Discussion forums additionally provide the means to preserve and revisit discussions.

The back-end server that provides the Discussion service manages content in a hierarchy. At the top of the hierarchy are categories, below that are forums, and then topics. Where categories are exposed in your WebCenter application, authorized users can create multiple forums within a given scope and multiple topics under those forums. Where categories are not exposed, authorized users can create multiple topics under one forum within a given scope.

17.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 (frequently viewed) topics

  • Most recent topics

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 17.2.3, "Setting Security for Discussions."

The Discussions service is integrated with many WebCenter 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. Use the Documents service to attach files to discussion threads, and use the Tags service to tag discussion threads help users to search for specific topics.

17.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.

17.1.3 What Happens at Runtime

To create forums in custom WebCenter applications, you must be a moderator or administrator on the back-end discussion server. For more information, see the "Granting Administrator Role for Oracle WebCenter Discussions Server" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

Figure 17-1 shows a discussion forum at runtime.

Figure 17-1 Discussion Forum at Runtime

Description of "Figure 17-1 Discussion Forum at Runtime"

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."

17.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 17.2.1, "Setting up Connections for Discussions"

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

• Section 17.2.3, "Setting Security for Discussions"

17.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. You can register additional WebCenter Discussion connections, but only one connection is active at a time.

When you create a WebCenter Discussion connection or set a connection as active, both the Announcements and Discussions services use this same connection. If you have an existing connection, then you can skip this section and see Section 17.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.

17.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.

17.2.1.2 How to Set Up Connections for Discussions

Follow these steps to set up the discussions connection.

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

   Note:

   If you created a WebCenter Discussion connection for the Announcements service, then that is used by default for the Discussions service. No extra configuration is required.

   However, to use different WebCenter Discussion connection for the Announcements service and the Discussions service, then a manual entry in adf-config.xml is required.

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

3. On the Name page, select to create the connection in Application Resources. (A connection in Application Resources is available only for that application, while a connection in IDE Connections is 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.)

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

5. Select the Set the default connection checkbox. You can have multiple connections, 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 17-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 17-2 Create Discussion Connections, Step 1

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

6. Click Next.

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

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

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

   • forum.connection.secure: Indicates that a secure communication is required between the custom WebCenter application and the Discussions server. You must set this value to true.

     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, and additional configuration about Web Services Security (WS-Security) is required on the next page. For more information, see the section "Configuring WS-Security" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter and see the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

8. Optionally, enter a value for the other parameter:

   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 cancels the connection and reports an error.

   Figure 17-3 Create Discussions Connection, Step 2

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

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

10. On the Create Discussion Connection - Step 3 of 3 page, you must configure client-side WS-Security (Figure 17-4).

    First obtain the client-side certificate and store it in a local directory. For more information, see the section "Configuring WS-Security" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

    Click the Add Property or Add Secured Property button to add each of the following WS-Security parameters:

    • 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. Add this as a secured property.

    • 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. Add this is as a secured property.

    Note:

    To encrypt property values, such as passwords, click the Add Secured Property button.

    Ensure that the property values match those in the certificate.

    Figure 17-4 Create Discussions Connection, Step 3

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

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

17.2.2 Adding the Discussions Service at Design Time

This section explains a basic incorporation of the Discussions service.

17.2.2.1 Discussions Task Flows

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

Table 17-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. All watched forums and topics are accessible from this task flow. The Watched Forums and Watched Topics task flows provide more focussed views of watched forums or watched topics. The parameters alter the way the view appears. For more information, see Section 17.3.1, "Customizing Discussions Views."
Discussions - Popular Topics	This task flow provides a view that allows users to see the most frequently viewed topics in the application under a given category ID or forum ID. For more information, see Section 17.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 in the application given a category ID or forum ID. For more information, see Section 17.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 in the application under a given category ID. For more information, see Section 17.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 in the application under a given category ID or forum ID. For more information, see Section 17.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 dropdown list so that end users can personalize it For more information, see Section 17.3.6, "Adding the Discussions - Sidebar View Task Flow."

17.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 4.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 17-2 describes the parameters.

   Note:

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

   Table 17-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 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 multiple Discussion Forums task flow instances. 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 22, "Integrating the Links Service."

• For users' presence indicators to work, you must have configured the Oracle WebCenter Presence service. For more information, see Chapter 18, "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.

17.2.3 Setting Security for Discussions

By default, authenticated users of custom WebCenter applications can view and participate in discussion forums. Any user who has logged in to a custom WebCenter application can view discussions; and users with sufficient permissions can create forums and topics. To create forums in custom WebCenter applications, you must be a moderator or administrator on the back-end discussion server that provides the WebCenter Discussions service.

In an unsecured custom WebCenter application, the user identity is not propagated to the Discussions server; consequently, users are identified as GUEST (that is, as anonymous users) and can view only public categories and forums.

Note:

Categories and forums are server-side classifications that move from category to forum to topic. That is, a category can head a collection of forums, just as a forum can head a collection of topics.

In a secured custom WebCenter application, discussions permissions are allotted according to an individual user's assigned user role. For example, a user can be a moderator, participant, or viewer. A forum moderator can edit and delete any topics and messages within a forum. A forum participant can create topics and edit his or her own topics. A forum viewer can view topics and messages.

In a non-secured custom WebCenter application, identity propagation cannot happen. A user is 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 is 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."

17.3 Advanced Information for the Discussions Service

This section describes optional features available with this service. It contains the following subsections:

• Section 17.3.1, "Customizing Discussions Views"

• Section 17.3.2, "Adding the Discussions - Popular Topics Task Flow"

• Section 17.3.3, "Adding the Discussions - Recent Topics Task Flow"

• Section 17.3.4, "Adding the Discussions - Watched Forums Task Flow"

• Section 17.3.5, "Adding the Discussions - Watched Topics Task Flow"

• Section 17.3.6, "Adding the Discussions - Sidebar View Task Flow"

• Section 17.3.7, "Obtaining Group Space RSS News Feed URL for the Discussions Service"

• Section 17.3.8, "Using Custom Discussions APIs"

• Section 17.3.9, "Using the Discussions Service REST APIs"

• Section 17.3.10, "Troubleshooting the Discussions Service"

17.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 are multiple forums. If there is only one forum, then it drills into the forum and lists 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 are multiple forums. 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 (that is, all forums listed under the root category) in a custom WebCenter application.

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

Figure 17-5 shows the Discussion Forums view with the value of isCategoryView left blank. All forums under the root category are listed.

Figure 17-5 Discussions Forum View with categoryId Set

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

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

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

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

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

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

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

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

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

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

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

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

17.3.2 Adding the Discussions - Popular Topics Task Flow

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

Note:

Popular topics are based on topic replies. The administrator is not able to determine popularity.

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 17.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Popular Topics onto the page.

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

Table 17-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 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 17-10 shows how the Discussions - Popular Topics task flow looks at runtime.

Figure 17-10 Discussions - Popular Topics View at Runtime

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

17.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 (that is, topics posted within the past two days) 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 17.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Recent Topics onto the page.

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

Table 17-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 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 17-11 shows how the Discussions - Recent Topics task flow looks at runtime. To view a topic post, simply click the relevant topic.

Figure 17-11 Discussions - Recent Topics View at Runtime

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

17.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.

You can watch discussion forums and topics to keep a close eye on the information most current and relevant to your efforts. The forums and topics you select to watch are personal, in that your selections appear on your view of watch lists. No other user is affected by the forums and topics you choose to watch.

When a user places a watch on a forum or a topic, whenever users add to that forum or topic, in addition to it appearing in the user's watched forums or topics list, the user receives an mail notification.

All watched forums and topics are accessible from the Forums task flow. The Watched Forums and Watched Topics task flows provide more focussed views of watched forums or watched topics.

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 17.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Watched Forums onto the page.

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

Table 17-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 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 17-12 shows how the Discussions - Watched Forums task flow looks at runtime.

Figure 17-12 Discussions - Watched Forums View at Runtime

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

For information on how to watch a forum or topic at runtime, see "Working with the Discussions Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter.

17.3.5 Adding the Discussions - Watched Topics Task Flow

Similar to the Discussions - Watched Forums 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 17.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Watched Topics onto the page.

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

Table 17-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 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 17-13 shows how the Discussions - Watched Topics task flow looks at runtime.

Figure 17-13 Discussions - Watched Topics View at Runtime

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

For information on how to watch a forum or topic at runtime, see "Working with the Discussions Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter.

17.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 17.2.2.2, "How to Add Discussions to your Application," but drag and drop Discussions - Sidebar View onto the page.

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

Figure 17-14 Discussions - Sidebar View at Runtime

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

17.3.7 Obtaining Group Space RSS News Feed URL for the Discussions Service

You can expose Oracle WebCenter Spaces functionality in a custom WebCenter application. Your custom application users can find out what is happening in a specific group space through RSS news feeds.

Configure RSS news feeds for the Discussions service to enable users to view group space discussions from within a custom application. To obtain the group space RSS news feed URL for the Discussions service, use either of the following WebCenter Spaces APIs:

• getServiceRSSFeedURL

• getServiceRSSFeedURLbyGuid

To obtain an RSS feed URL, you must identify the group space (by name or GUID) and specify the service required (by service ID). The service ID for the Discussions service is GroupSpaceWSClient.DISCUSSION_SERVICE_ID.

For information about how to use these APIs, see Section 27.2.5.3.8, "Retrieving RSS Feed URLs for Group Space Services."

17.3.8 Using Custom Discussions APIs

The back-end Oracle WebCenter Discussions server includes APIs to further customize your application. To learn more about them, see the Jive Forums documentation on the Oracle Fusion Middleware documentation library (in the WebCenter product area).

17.3.9 Using the Discussions Service REST APIs

Oracle WebCenter provides REST APIs to support the Discussions service. Use the Discussions service REST APIs to post, read, update, and delete discussion forums, topics, and messages.

This section describes the REST APIs associated with the Discussions service. It contains the following subsections:

• Section 17.3.9.1, "Discussions Entry Point"

• Section 17.3.9.2, "Discussions Resource Type Taxonomy"

• Section 17.3.9.3, "Security Considerations"

• Section 17.3.9.4, "Discussions Resource Types"

For an introduction to the REST APIs, see Section 28, "Using Oracle WebCenter REST APIs."

17.3.9.1 Discussions Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. To find the entry point for the Discussions service, find the link element with a resourceType of:

urn:oracle:webcenter:discussions:forums

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with the Discussions service.

For more information about the Resource Index, see Section 28.3.1, "The Resource Index."

For more information about resource types, see Section 28.3.2.1, "Resource Type."

17.3.9.2 Discussions Resource Type Taxonomy

When the client has identified the entry point, it can then navigate through the resource type taxonomy to perform the required operations. For more information about the individual resource types, see the appropriate section in Section 28.3.2.1, "Resource Type."

The taxonomy for the Discussions service is:

urn:oracle:webcenter:discussions:forums
   urn:oracle:webcenter:discussions:forum
   urn:oracle:webcenter:discussions:forum:topics
      urn:oracle:webcenter:discussions:forum:topic
      urn:oracle:webcenter:discussions:forum:topic:messages
         urn:oracle:webcenter:discussions:forum:topic:message

Beyond the service entry points, URL templates allow clients to pass query parameters to customize their requests and control the form of returned data.

Collection resources in the discussions resources support pagination (startIndex and itemsPerPage). Other query parameters are not supported (that is, search and projection).

17.3.9.3 Security Considerations

There are no specific security considerations for this service. For general security considerations, see Section 28.6, "Security Considerations for WebCenter REST APIs."

17.3.9.4 Discussions Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following subsections:

• Section 17.3.9.4.1, "urn:oracle:webcenter:discussions:forums"

• Section 17.3.9.4.2, "urn:oracle:webcenter:discussions:forum"

• Section 17.3.9.4.3, "urn:oracle:webcenter:discussions:forum:topics"

• Section 17.3.9.4.4, "urn:oracle:webcenter:discussions:forum:topic"

• Section 17.3.9.4.5, "urn:oracle:webcenter:discussions:forum:topic:messages"

• Section 17.3.9.4.6, "urn:oracle:webcenter:discussions:forum:topic:message"

17.3.9.4.1 urn:oracle:webcenter:discussions:forums

Use this resource type to identify the URI to use to read (GET) and write (POST) discussion forums. The response from a GET operation includes each forum in this collection of forums, and each forum includes links used to operate on that forum. The response from a POST operation includes the forum that was created in this collection of forums and a link to operate on that forum.

Navigation Paths to forums

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums

Supported Methods for forums

The following methods are supported by this resource:

• GET

  • request - body: none, Parameters: startIndex, itemsPerPage (pagination)

  • response - body: forums

• POST

  • request - body: forum

  • response - body: forum

For more information, see Section 28.3.2.5, "Templates."

Resource Types Linked to From forums

Table 17-7 lists the resource types that the client can link to from this resource.

Table 17-7 Related Resource Types for forums

rel	resourceType
self	urn:oracle:webcenter:discussions:forums
	urn:oracle:webcenter:discussions:forum

17.3.9.4.2 urn:oracle:webcenter:discussions:forum

Use this resource type to identify the URI to use to read (GET), update (PUT), and delete (DELETE) a specific discussion forum. The response from a GET operation includes the specific forum identified by the URI. The response from a PUT operation includes the modified version of the forum identified by the URI. The response from a DELETE operation is a 204.

Navigation Paths to forum

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      forum

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            forum

resourceindex
   activities
      forum

Supported Methods for forum

The following methods are supported by this resource:

• GET

  • request - body: none

  • response - body: forum

• PUT

  • request - body: forum

  • response - body: forum

• DELETE

  • request - body: none

  • response - body: none

Writable Elements for forum

Table 17-2 lists the writable elements for this resource.

Table 17-8 Writable Elements for forum

Element	Type	Required	Constraints	Description
name	String	Yes	1 or more characters	Name of the forum
displayName	String	No	1 or more characters	Name used in presentation
description	String	No	1 or more characters	Description of the forum

Read-only Elements for forum

Table 17-2 lists the read-only elements for this resource.

Table 17-9 Read-only Elements for forum

Element	Type	Description
id	Integer	ID of the forum
parentId	Integer	ID of the parent category
createdBy	String	User that created the forum
createdOn	Date	Date on which the forum was created
updatedBy	String	User that performed the last modification
updatedOn	Date	Date on which the forum was last modified
webUrl	String	URL for direct access to the Oracle WebCenter Discussions server
topicCount	Integer	Number of topics
messageCount	Integer	Number of messages
locked	Boolean	True if this forum is locked
favorite	Boolean	True if this forum is marked as a favorite

Resource Types Linked to From forum

Table 17-10 lists the resource types that the client can link to from this resource.

Table 17-10 Related Resource Types for forum

rel	resourceType
self	urn:oracle:webcenter:discussions:forum
	urn:oracle:webcenter:discussions:forum:topics

17.3.9.4.3 urn:oracle:webcenter:discussions:forum:topics

Use this resource type to identify the URI to use to read (GET) and write (POST) discussion topics. The response from a GET operation includes each topic in this collection of topics, and each topic includes links used to operate on that topic. The response from a POST operation includes the topic that was created in this collection of topics and a link to operate on that topic.

Navigation Paths to topics

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      topics

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            topics

Supported Methods for topics

The following methods are supported by this resource:

• GET

  • request - body: none, Parameters: startIndex, itemsPerPage (pagination)

  • response - body: topics

• POST

  • request - body: topic

  • response - body: topic

For more information, see Section 28.3.2.5, "Templates."

Resource Types Linked to From topics

Table 17-11 lists the resource types that the client can link to from this resource.

Table 17-11 Related Resource Types for topics

rel	resourceType
self	urn:oracle:webcenter:discussions:forum:topics
	urn:oracle:webcenter:discussions:forum:topic

17.3.9.4.4 urn:oracle:webcenter:discussions:forum:topic

Use this resource type to identify the URI to use to read (GET), update (PUT), and delete (DELETE) a specific discussion topic. The response from a GET operation includes the specific topic identified by the URI. The response from a PUT operation includes the modified version of the topic identified by the URI. The response from a DELETE operation is a 204.

Navigation Paths to topic

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      topics
         topic

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            topics
               topic

resourceindex
   activities
      topicT

Supported Methods for topic

The following methods are supported by this resource type:

• GET

  • Request—Body: none

  • Response—Body: topic

• PUT

  • Request—Body: topic

  • Response—Body: topic

• DELETE

  • Request—Body: none

  • Response—Body: none

Writable Elements for topic

Table 17-12 lists the writable elements for this resource type.

Table 17-12 Writable Elements for topic

Element	Type	Required	Constraints	Description
subject	String	Yes	1 or more characters	Subject of the topic
body	String	No	0 or more characters	Contents of the topic

Read-only Elements for topic

Table 17-13 lists the read-only elements for this resource type.

Table 17-13 Read-only Elements for topic

Element	Type	Description
id	Integer	Identifier for the topic
parentId	Integer	Identifier for the parent message
forumId	Integer	Identifier for the forum under which this topic is posted
topicId	Integer	Identifier for the topic under which this topic is posted
createdBy	String	User who created the topic
createdOn	Date	Date on which the topic was created
updatedBy	String	User who lasted updated the topic
updatedOn	Date	Date on which the topic was last updated
webUrl	String	URL for direct access to the Oracle WebCenter Discussions server
depth	Integer	Depth in the hierarchy of messages
messageCount	Integer	Number of child messages under this topic
numberOfReplies	Integer	Number of replies to this topic
favorite	Boolean	Whether the topic is marked as a favorite for the user
locked	Boolean	Whether the topic is locked
hidden	Boolean	Whether the topic is hidden
hasAttachment	Boolean	Whether the topic has attachments

Resource Types Linked to From topic

Table 17-14 lists the resource types that the client can link to from this resource.

Table 17-14 Related Resource Types for topic

rel	resourceType
self	urn:oracle:webcenter:discussions:forum:topic
	urn:oracle:webcenter:discussions:forum:topic:messages

17.3.9.4.5 urn:oracle:webcenter:discussions:forum:topic:messages

Use this resource type to identify the URI to use to read (GET) and write (POST) discussion topic messages. The response from a GET operation includes each message in this collection of messages, and each message includes links used to operate on that message. The response from a POST operation includes the message that was created in this collection of messages and a link to operate on that message.

Navigation Paths to messages

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      topics
         messages

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            topics
               messages

Supported Methods for messages

The following methods are supported by this resource:

• GET

  • request - body: none, Parameters: startIndex, itemsPerPage (pagination)

  • response - body: messages

• POST

  • request - body: message

  • response - body: message

For more information, see Section 28.3.2.5, "Templates."

Resource Types Linked to From messages

Table 17-15 lists the resource types that the client can link to from this resource.

Table 17-15 Related Resource Types for messages

rel	resourceType
self	urn:oracle:webcenter:discussions:forum:topic:messages
	urn:oracle:webcenter:discussions:forum:topic:message

17.3.9.4.6 urn:oracle:webcenter:discussions:forum:topic:message

Use this resource type to identify the URI to use to read (GET), update (PUT), and delete (DELETE) a specific discussion topic message. The response from a GET operation includes the specific message identified by the URI. The response from a PUT operation includes the modified version of the message identified by the URI. The response from a DELETE operation is a 204.

Navigation Paths to message

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      topics
         messages
            message
 

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            topics
               messages
                  message

Supported Methods for message

The following methods are supported by this resource:

• GET

  • request - body: none

  • response - body: message

• PUT

  • request - body: message

  • response - body: message

• DELETE

  • request - body: none

  • response - body: none

Writable Elements for message

Table 17-16 lists the writable elements for this resource.

Table 17-16 Writable Elements for message

Element	Type	Required	Constraints	Description
subject	String	Yes	1 or more characters	Subject of this message
body	String	No	0 or more characters	Content of this message

Read-only Elements for message

Table 17-17 lists the read-only elements for this resource.

Table 17-17 Read-only Elements for message

Element	Type	Description
id	Integer	ID of the message
parentId	Integer	ID of the parent message
forumId	Integer	ID of the forum under which the message is posted
topicId	Integer	ID of the topic under which the message is posted
createdBy	String	User that created the message
createdOn	Date	Date on which the message was created
updatedBy	String	User that performed the last modified
updatedOn	Date	Date on which the message was last modified
webUrl	String	URL for direct access to the Oracle WebCenter Discussions server
depth	Integer	Depth in the hierarchy of messages
messageCount	Integer	Number of messages
numberOfReplies	Integer	Number of replies to this message
hidden	Boolean	True if this message is hidden
hasAttachment	Boolean	True if this message has attachments

Resource Types Linked to From message

Table 17-18 lists the resource types that the client can link to from this resource.

Table 17-18 Related Resource Types for message

rel	resourceType
self	urn:oracle:webcenter:discussions:forum:topic:message
	urn:oracle:webcenter:discussions:forum:topic:messages

17.3.10 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 Identity Store" 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.

Problem

If you change the connection to use a different Discussions server, and if you change the application root category ID from administrator-services-discussions, then you could see exceptions like, "Category Not Found."

Solution

Restart the managed server on which the WebCenter application is deployed.