32 Integrating the Announcements Service

This chapter explains how to integrate the Announcements service into a WebCenter Portal application at design time. For more information about managing and including announcements, see:

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

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

This chapter includes the following sections:

• Section 32.1, "Introduction to Announcements"

• Section 32.2, "Basic Configuration for the Announcements Service"

• Section 32.3, "Advanced Information for the Announcements Service"

32.1 Introduction to Announcements

The Announcements service lets you create and expose announcements on your application pages. Access to announcements boosts community participation, problem resolution, and knowledge sharing.

You can use the Links service to link announcements to other services, such as Events or Discussions. For example, suppose your company is announcing a new product, you can link from the announcement directly to a discussion forum, where potential customers can ask other customers about the product, or link to an instant messenger to speak directly with a customer service representative to purchase the product.

Announcements can show either forum-level announcements or global announcements (that is, system announcements not specific to a forum).

This section includes the following subsections:

• Section 32.1.1, "Understanding the Announcements Service"

• Section 32.1.2, "Requirements for Announcements"

• Section 32.1.3, "What Happens at Runtime"

32.1.1 Understanding the Announcements Service

With the Announcements service, you can do the following:

• Create announcements.

• Edit and delete existing announcement.

• Mail announcements.

• Personalize the Announcements view. You can select to display all announcements or only announcements sent today, this week, or this month. You can also view future, active, or expired announcements.

• Manage announcements, such as publishing announcements on a later date and specifying auto-expire on certain dates.

The Announcements service is integrated with many WebCenter services, such as RSS, Search (to search announcement text), Instant Messaging and Presence (IMP), and Recent Activities. Use the Links service to link announcements to other services, such as Discussions.

32.1.2 Requirements for Announcements

The Announcements service requires a discussions server. You must install and configure the discussions server that comes with Oracle Fusion Middleware.

For information on installing the discussions server, see Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

32.1.3 What Happens at Runtime

At runtime, users who have been granted the create permission can post announcements, and these announcements are visible to all users who have view permission. For example, an application administrator can use this service to announce the availability of a new feature or the plan to shut down the application temporarily for maintenance.

Figure 32-1 shows a sample announcement at runtime.

Figure 32-1 Sample Announcement in the Announcements - Quick View Task Flow

Description of "Figure 32-1 Sample Announcement in the Announcements - Quick View Task Flow"

To view announcements in the Announcement Manager, ensure that the Announcements task flow has been added to your application. Then log in to your WebCenter application and click the Open Announcement Manager icon in the Announcements task flow (Figure 32-2).

Figure 32-2 Open Announcement Manager Icon

Description of "Figure 32-2 Open Announcement Manager Icon"

Note:

The Open Announcement Manager icon does not display if the user does not have the required privileges.

Figure 32-3 shows the sample announcement in the Announcement Manager.

Figure 32-3 Sample Announcement in the Announcement Manager

Description of "Figure 32-3 Sample Announcement in the Announcement Manager"

Application administrators in WebCenter applications can access the Announcement Manager, which provides Create, RSS, and Refresh icons, and Show dropdown lists to control the display of announcements on the page. Edit, Delete, Mail, and Links icons are available for each announcement in the list.

Depending on the privileges users have on the page and whether the required WebCenter services are configured in the application, users may see only a subset of these options in the Announcement Manager. For example, the Delete icon is displayed only to users with administrative privileges.

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

32.2 Basic Configuration for the Announcements Service

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

• Section 32.2.1, "Setting Up a Connection for Announcements"

• Section 32.2.2, "Adding the Announcements Service at Design Time"

• Section 32.2.3, "Setting Security for Announcements"

32.2.1 Setting Up a Connection for Announcements

To take advantage of the Announcements service, you must first create a connection to the discussions server from your WebCenter Portal application. To do so, ensure that you have the connection information for the discussions server.

32.2.1.1 Announcements Connections

The Announcements 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 32.2.2, "Adding the Announcements Service at Design Time."

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

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.

32.2.1.2 How to Set Up Connections for Announcements

To set up the Announcements connection:

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

   Note:

   If you created a WebCenter Discussion connection for the Discussions service, then that is used by default for the Announcements service. No extra configuration 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.)

   Note:

   If you create 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.

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

5. Select the Set as 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 active connection (Figure 32-4).

   Note:

   After you create a connection as the active 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 32-4 Create Discussion Connections, Step 1

   
   Description of "Figure 32-4 Create Discussion Connections, Step 1"
   
   

6. Click Next.

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

   • URL: Enter the URL of the discussions server hosting discussion forums and announcements. For example: http://discussions.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.

     In WebCenter Spaces, this account is mostly used for managing Space-related discussions and announcements. It is not necessary for this user to be a super admin. However, the user must have administrative privileges on the current root category for WebCenter Spaces, that is, the category (on the discussions server) under which all Space-related discussions and announcements are stored.

     Note:

     If your WebCenter application does not include Space-related functionality, the administrator's user name is not required.

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

   • Connection Timeout: Specify a suitable timeout for the connection. This is the length of time (in seconds) the WebCenter Portal application waits for a response from the discussions server before issuing a connection timeout message. The default is -1, which means that the service default is used. The service default is 10 seconds.

   • Policy URI for Authenticated Access: Select the SAML token client policy this connection uses for authenticated access to the discussions server Web service. SAML (Security Assertion Markup Language) is an XML-based standard for passing security tokens defining authentication and authorization rights. An attesting entity (that has trust relationship with the receiver) vouches for the verification of the subject by method called sender-vouches. Options available are:

     • WSS 1.0 SAML Token Client Policy (oracle/wss10_saml_token_client_policy)

     • WSS 1.1 SAML Token With Message Protection Client Policy (oracle/wss11_saml_token_with_message_protection_client_policy)

     The client policy specified must be compatible with the service policy that is configured for the OWCDiscussionsServiceAuthenticated endpoint in the discussions server. Out-of-the-box, the default service policy is WSS 1.0 SAML Token Service Policy (oracle/wss10_saml_token_service_policy).

   • Policy URI for Public Access: Select the client policy this connection uses to enforce message security and integrity for public access to the discussions server Web service. Options available are:

     • None - This is the default setting.

     • WSS 1.1 Message Protection Client Policy (oracle/wss11_with_message_protection_client_policy)

     The client policy specified must be compatible with the service policy that is configured for the OWCDiscussionsServicePublic endpoint in the discussions server. Out-of-the-box, a service policy is not configured for public access.

   • Recipient Key Alias: Enter the recipient key alias to be used for message protected policies (applicable to the OWCDiscussionsServicePublic and OWCDiscussionsServiceAuthenticated endpoints). This is the alias to the certificate that contains the public key of the discussions server in the configured keystore.

     For more information, see the chapter "Configuring WS-Security for WebCenter Portal Applications and Components" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

   Figure 32-5 Create Discussions Connection, Step 2

   
   Description of "Figure 32-5 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 can configure additional parameters. For example:

    application.root.category.id: (WebCenter Spaces only) The application root category ID on the discussions server under which all discussion forums are stored. For example, if set to 3, then all forums are stored inside the category 3.

    Note:

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

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

32.2.2 Adding the Announcements Service at Design Time

This section explains a basic incorporation of the Announcement service.

32.2.2.1 Announcements Service Task Flows

Both the Announcements and the Announcements - Quick View task flows display current announcements. The Announcements task flow additionally offers tools for managing announcements within the task flow. With the Announcements - Quick View task flow, you must click the Open Announcement Manager icon to manage announcements, and administrators can configure this task flow to remove all announcement management functionality.

Table 32-1 Announcements Service Task Flows

Task Flow	Description
Announcements	This task flow displays a view that allows the user to see all current announcements and perform operations based on their privileges. For a Moderator, all command buttons are shown, but for a Reader, only the refresh and personalization options are shown. The personalization option lets users select the number of days to display announcements. The parentId parameter is the forum ID in the discussions server under which announcements are maintained. Each WebCenter Portal application should create a forum on the Discussions server.
Announcements - Quick View	This task flow displays a view that shows various categories of quick links to announcements. The parentId parameter is the forum ID in the discussions server under which announcements are maintained. Each WebCenter Portal application should create a forum on the Discussions server. The look and feel of this view changes with the optional parameter values given for rendering the task flow region. For information on how to add this task flow, see Section 32.3.1, "How to Add the Announcements - Quick View Task Flow."

32.2.2.2 How to Add Announcements to Your Page

The Announcements task flow provides a complete view of your announcements. To add the Announcements task flow to your WebCenter Portal application:

1. Follow the steps described in Chapter 3, "Preparing Your Development Environment" to implement security and create a new customizable page in your application.

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

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

4. Drag Announcements from the Resource Palette and drop it onto the page inside of the af:form begin and end tags.

5. When prompted, select Region as the way to create the task flow (and confirm with Add Library). This operation may take a moment to complete.

6. In the Edit Task Flow Binding dialog, enter a value for the parentId parameter.

   The Discussions Server could be shared with multiple WebCenter Portal applications. Each WebCenter Portal application should create a forum on the Discussions server. Enter that forum ID here as the parentId; for example, ${2}.

7. Click OK.

8. Save and run your page.

32.2.2.3 How to Modify Announcements Service Task Flow Parameters

The Announcements service task flows have required and optional task flow binding parameters.

You can adjust the parameter values when you drop the task flows onto a page or after you have placed a task flow on a page:

1. Navigate to the Edit Task Flow Binding dialog by clicking the Bindings tab at the bottom of the page (next to the Source tab).

2. Under Executables, you'll see the task flow you added. Figure 32-6 shows an example of a Search task flow in the Executables section.

   Figure 32-6 Page Data Binding Definition

   
   Description of "Figure 32-6 Page Data Binding Definition"
   
   

3. Select the task flow, and next to the Executables heading, click the Edit selected element (pencil) icon.

4. In the Edit Task Flow Binding dialog Figure 32-7, revise the binding parameter values as required.

   Figure 32-7 Edit Task Flow Binding Dialog for Announcements - Quick View

   
   Description of "Figure 32-7 Edit Task Flow Binding Dialog for Announcements - Quick View"
   
   

5. When you are finished, click OK.

6. Save and run your page to see the results.

Table 32-2 describes the properties that are unique to the Announcements service task flows.

Table 32-2 Announcements Service Task Flow Parameters

Property	Description	Task Flow
parentId	The forum ID in the discussions server under which announcement objects are maintained. Each WebCenter Portal application should create a forum on the Discussions server. Enter that forum ID here; for example, ${2}. If this parameter is not specified, then announcements default to global announcements.	Announcements Announcements - Quick View
freeFlowView	A Boolean value representing whether to remove the announcement title (subject) and show the announcement body as is. The default value is ${false}, which means that the announcement list displays the title and body in plain text and the truncateAt and expandedAnnouncements parameters control it. Enter ${true} to remove the announcement title and ignore the values for truncateAt and expandedAnnouncements.	Announcements - Quick View
expandedAnnouncements	The number of announcements to display announcement details (that is, the body of the announcement). Users can click the title to display the full announcement content in rich text mode. The value you enter for expandedAnnouncements is ignored if freeFlowView is set to true.	Announcements - Quick View
truncateAt	For announcements that display announcement body, this value specifies how many characters to display for each announcement. Enter an Expression Language (EL) expression. For example, when the value is set to the EL expression ${50}, following their titles, announcements display no more than 50 characters. Users can click announcement titles to display the full announcement. If no value is specified, then it displays 200 characters. If a non-valid positive integer value is specified, then it displays all characters in plain text. This parameter takes effect with expandedAnnouncements. The value you enter for truncateAt is ignored if freeFlowView is set to true.	Announcements - Quick View
pageSize	The number of announcements to show in a page on Extended Quick View.	Announcements - Quick View
visibleAnnouncements	The number of announcements to show in the Quick View.	Announcements - Quick View
hideToolbar	A Boolean value representing whether to display the task flow personalization feature.	Announcements - Quick View
navigateToAnnouncementViewer	A Boolean value representing whether to launch the announcement in a popup or navigate to the Announcement Manager. The default behavior is to launch in a popup. Enter true to navigate to the Announcement Manager.	Announcements - Quick View
expandAllAnnouncements	A Boolean value representing whether to display details for all announcements in extended quick view. Default value is false, in which case announcements display the announcement title only.	Announcements - Quick View

You can change the look and feel of the Announcements - Quick View with the parameter values. For example, Figure 32-12 shows the Announcements - Quick View at runtime with the freeFlowView parameter set to false (or empty).

Figure 32-8 Announcements - Quick View with Optional Parameters

Description of "Figure 32-8 Announcements - Quick View with Optional Parameters"

Figure 32-13 shows the Announcements - Quick View at runtime with the freeFlowView parameter set to ${true}.

Figure 32-9 Announcements - Quick View with freeFlowView Parameter

Description of "Figure 32-9 Announcements - Quick View with freeFlowView Parameter"

32.2.3 Setting Security for Announcements

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

In an unsecured WebCenter Portal application, identity propagation cannot happen. A user is a guest (or anonymous) user who can view only public categories and forums. In an unsecured application, the parentId (forum ID) from which announcements are fetched should be a public forum. If the forum is not public, then an error is reported. If the parentId parameter is not specified at all, then WebCenter cannot fetch global announcements (that is, announcements not scoped to a forum): global announcements are not available for public users. Rather than relying to global announcements, each WebCenter Portal application should reserve its own forum ID.

In an ADF-secured WebCenter Portal 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 WebCenter Portal application point to the same identity store. This way, your users can log in to the application one time and automatically connect to the discussions server.

Note:

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

ADF security is configured by default if you created your application using the WebCenter Portal Application template. For information about configuring ADF security, see Section 67.3, "Configuring ADF Security."

32.3 Advanced Information for the Announcements Service

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

• Section 32.3.1, "How to Add the Announcements - Quick View Task Flow"

• Section 32.3.2, "Customizing Announcements Views"

• Section 32.3.3, "Obtaining Space RSS News Feed URL for the Announcements Service"

32.3.1 How to Add the Announcements - Quick View Task Flow

The Announcements - Quick View provides a snapshot (dashboard) view of the announcements (Figure 32-10).

Figure 32-10 Announcements - Quick View

Description of "Figure 32-10 Announcements - Quick View"

By default, announcements in the Announcements - Quick View task flow show announcement titles as links. But you can configure the task flow to display only announcement titles, titles with some amount of content, or only content.

Click an announcement to view it in a popup. From there, you can select the Mail icon to mail the announcement to anyone you choose or select the Links icon to link to this announcement (Figure 32-10).

Figure 32-11 Announcement Popup

Description of "Figure 32-11 Announcement Popup"

The Announcements - Quick View task flow includes numerous parameters to customize your view. For example, you can remove the link to the Announcement Manager, to present announcements to end users where manage controls are not needed. The task flow lists 10 announcements by default, but you can change this number and how much of the announcement is displayed. The More Announcements ... link launches a popup containing the complete list of all announcements with pagination behavior. This is called the Extended Quick View (or Mini View).

To add the Announcements - Quick View to your WebCenter Portal application, follow the same instructions that you did for the Announcements task flow in Section 32.2.2, "Adding the Announcements Service at Design Time," but drag and drop Announcements - Quick View onto the page.

Table 32-2 describes the Announcements - Quick View parameters. The look and feel of the Announcements - Quick View changes with the values provided for these parameters. For more information, see Section 32.2.2.3, "How to Modify Announcements Service Task Flow Parameters."

32.3.2 Customizing Announcements Views

You can change the look and feel of the Announcements - Quick View with the parameter values. For example, Figure 32-12 shows the Announcements - Quick View at runtime with the freeFlowView parameter set to false (or empty).

Figure 32-12 Announcements - Quick View with Optional Parameters

Description of "Figure 32-12 Announcements - Quick View with Optional Parameters"

Figure 32-13 shows the Announcements - Quick View at runtime with the freeFlowView parameter set to ${true}.

Figure 32-13 Announcements - Quick View with freeFlowView Parameter

Description of "Figure 32-13 Announcements - Quick View with freeFlowView Parameter"

32.3.3 Obtaining Space RSS News Feed URL for the Announcements Service

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

Configure RSS news feeds for the Announcements service to enable users to view Space announcements from within a WebCenter Portal application. To obtain the Space RSS news feed URL for the Announcements service, use either of the following WebCenter Spaces APIs:

• getServiceRSSFeedURL

• getServiceRSSFeedURLbyGuid

To obtain an RSS feed URL, you must identify the Space (by name or GUID) and specify the service required (by service ID). The service ID for the Announcements service is GroupSpaceWSClient.ANNOUNCEMENT_SERVICE_ID.

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