50 Integrating Notifications

This chapter describes how to integrate notifications with a Portal Framework application. Notifications provide a means of subscribing to services and application objects and, when those objects change, receiving notification across selected messaging channels.

This chapter includes the following topics:

50.1 Introduction to Notifications

This section provides an overview of Notifications. It includes the following subsections:

50.1.1 Understanding Notifications

Notifications provides an automated means of triggering notices about subscribed services and objects across different messaging channels. Messages are triggered when the application services and objects to which a user has subscribed change. For example, a user can subscribe to a document and receive notification when another user changes the document.

Messaging channels can include phone text (SMS), mail, or Worklist, depending on what messaging servers are available and how the application administrator configures Notifications. For example, users can receive a mail message when a particular document changes, a text message when someone responds to a particular discussion topic, a Worklist alert when the user receives an invitation to connect. All messages contain links that take the user to the scene of the change.

Participating services and objects include People Connections (Connections, Message Board, and Feedback), Discussions, and Documents (including Wikis and Blogs).

Table 50-1 describes the types of activities that can trigger a notification and indicates the level at which the subscription is made.

Table 50-1 Activities that Can Trigger Notifications

Activity Level

A user sends you an invitation to connect

Application

A user posts a message to your Message Board

Application

A user likes your Message Board post (messages explicitly set on a Message Board and not those added from Publisher to the Activity Stream)

Application

A user comments on your Message Board post (messages explicitly set on a Message Board and not those added from Publisher to the Activity Stream)

Application

A user posts feedback for you

Application

A user replies to a discussion topic

Object

A user comments on a discussion topic

Object

A user deletes a discussion topic

Object

A user comments on a document

Object

A user likes a document

Object

A user updates a document

Object

A user deletes a document

Object

A user comments on a wiki document

Object

A user likes a wiki document

Object

A user updates a wiki document

Object

A user deletes a wiki document

Object

A user comments on a blog entry

Object

A user likes a blog entry

Object

A user updates a blog entry

Object

A user deletes a blog entry

Object

Notifications leverages message delivery platforms available in WebCenter, such as the User Messaging Service (UMS) or the Mail service, to deliver the messages it generates. The Mail service furnishes the default messaging delivery mechanism, though you can instead use the BPEL connection provided through the Worklist service to widen a user's choice of channels to phone text, mail, and the Worklist.

You can set defaults for application-level subscriptions for all users through an XML configuration file (notification-service-settings.xml). You create your own version of this default file, and then use it to supersede the file of the same name that is provided for this purpose out of the box.

50.1.2 Requirements for Notifications

Before your application can work with the Notifications service, you must specify the Notification namespace in the application's adf-config.xml file. For more information, see Section 50.2.1, "Adding the Notifications Namespace."

Subscription capability is built into the services that support it and does not require additional configuration.

Notifications messaging capability relies on the presence of a configured Mail or Worklist connection to enable delivery of notifications messages. For Notifications messaging, you must explicitly configure the application to use either the BPEL server that is configured for the Worklist service or the Mail server that is configured for the Mail service. For more information, see Section 50.2.2, "Creating a Notifications Connection to a Mail Server," and Section 50.2.3, "Creating a Notifications Connection to a BPEL Server."

To set application defaults for all users for application-level subscription preferences, you must provide your own version of the default file notification-service-settings.xml. For more information, see Section 50.2.4, "Setting Application Defaults for Notifications."

For Notifications to function properly, its task flows must reside on a secured page. This is because the current user must be known through authentication in order to track and report on subscribed actions. If the page or application that contains Notifications is not secured, you will encounter exception errors. For more information, see Section 50.2.6, "Setting Security for Notifications."

50.1.3 What Happens with Notifications at Runtime

At runtime, users set up their preferred messaging channels through UMS Preferences. For more information, see the "Establishing and Managing Your Messaging Channels and Filters" section in Using Oracle WebCenter Portal.

Note:

In designing your application, you must provide users with a way to access UMS preferences. For example, you can add a link to them in your UI, or you can point users to the Worklist task flow, which includes a link to them.

Users establish their application-level subscriptions through the Notifications task flow Subscription Preferences. The task flow presents slightly different options depending on whether it is located on the Home portal (Figure 50-1) or a portal (Figure 50-2).

Figure 50-1 Subscription Preferences Task Flow - Home Portal

Description of Figure 50-1 follows
Description of ''Figure 50-1 Subscription Preferences Task Flow - Home Portal''

Figure 50-2 Subscription Preferences Task Flow - Portal

Description of Figure 50-2 follows
Description of ''Figure 50-2 Subscription Preferences Task Flow - Portal''

Users establish their object-level subscriptions by subscribing to the object directly.

Users manage their application-level subscriptions through the Subscription Preferences task flow and their object-level subscriptions through the Notifications task flow Subscription Viewer (Figure 50-3).

Figure 50-3 Subscription Viewer Task Flow

Description of Figure 50-3 follows
Description of ''Figure 50-3 Subscription Viewer Task Flow''

See Also:

For more information about Notifications task flows, see Section 50.2.5.1, "Notifications Task flows."

50.2 Basic Configuration for Notifications

Notifications leverages your Mail or Worklist service connection to provide messaging channels for user notifications. If you plan to use the Mail server, then a connection to a mail server for the Mail service is required, but no further configuration is necessary for Notifications. If you plan to use the same BPEL connection for Notifications that is used by the Worklist service, you must add this configuration to the adf-config.xml file.

This section provides an overview of those connections and configurations and the process of adding Notifications task flows to an application page. It includes the following subsections:

50.2.1 Adding the Notifications Namespace

To establish the Notifications namespace with your application, add the following code to the adf-config element at the top of the file (Example 50-1):

Tip:

You can find the adf-config.xml file in the Application Resources panel, under Descriptors, in the ADF META-INF folder.

Example 50-1 Configuring the Application to Recognize Notifications Configuration

xmlns:notificationC="http://xmlns.oracle.com/webcenter/notification/config"

For example (bold) (Figure 50-3):

Example 50-2 Notifications Configuration in the adf-config Element

<?xml version="1.0" encoding="US-ASCII" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
   xmlns:adf="http://xmlns.oracle.com/adf/config/properties"
   xmlns:sec="http://xmlns.oracle.com/adf/security/config"
   xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service"
   xmlns:jndiC="http://xmlns.oracle.com/adf/jndi/config"
   xmlns:worklistC="http://xmlns.oracle.com/webcenter/worklist/config"
   xmlns:notificationC="http://xmlns.oracle.com/webcenter/notification/config"
   xmlns:mdsC="http://xmlns.oracle.com/adf/mds/config"
   xmlns:searchC="http://xmlns.oracle.com/webcenter/search/config"
   xmlns:relC="http://xmlns.oracle.com/webcenter/relationship/config"
   …

50.2.2 Creating a Notifications Connection to a Mail Server

To enable users to select a mail messaging channel, you must configure a connection to a Mail server (for more information, see Section 35.2.2, "Setting up Connections for Mail"). Once this is established, you add the following entry in the adf-config.xml file to associate the Mail server with Notifications (Example 50-3).

Example 50-3 Associating a Mail Server with Notifications in adf-config.xml

<notificationC:adf-notification-config
      xmlns="http://xmlns.oracle.com/webcenter/notification/config">
   <ConnectionType>MAIL</ConnectionType>
   <ConnectionName>someMailConnection</ConnectionName>
</notificationC:adf-notification-config>

Where ConnectionName is the name of a configured Mail server.

Example 50-4 presents a code sample, with the previous code sample in place (bold).

Example 50-4 A Mail Connection for Notifications in adf-config.xml

<?xml version="1.0" encoding="US-ASCII" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
   xmlns:adf="http://xmlns.oracle.com/adf/config/properties"
   xmlns:sec="http://xmlns.oracle.com/adf/security/config"
   xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service"
   xmlns:jndiC="http://xmlns.oracle.com/adf/jndi/config"
   xmlns:worklistC="http://xmlns.oracle.com/webcenter/worklist/config"
   xmlns:notificationC="http://xmlns.oracle.com/webcenter/notification/config"
   xmlns:mdsC="http://xmlns.oracle.com/adf/mds/config"
   xmlns:searchC="http://xmlns.oracle.com/webcenter/search/config"
   xmlns:relC="http://xmlns.oracle.com/webcenter/relationship/config"
   xmlns:collabC="http://xmlns.oracle.com/webcenter/collab/config"
   xmlns:listC="http://xmlns.oracle.com/webcenter/list/config"
   xmlns:rcs="http://xmlns.oracle.com/adf/rcs/adf-config"
   xmlns:rcv="http://xmlns.oracle.com/adf/rcs/viewer/adf-config"xmlns:tagC=
      "http://xmlns.oracle.com/webcenter/tagging/config"
   xmlns:doclibC="http://xmlns.oracle.com/webcenter/doclib/config">
<adf:adf-properties-child xmlns="http://xmlns.oracle.com/adf/config/properties">
   <adf-property name="adfAppUID" value="ps3stage2app-7762"/>
</adf:adf-properties-child>
<sec:adf-security-child xmlns="http://xmlns.oracle.com/adf/security/config">
   <CredentialStoreContext
      credentialStoreClass="oracle.adf.share.security.providers.jps.
      CSFCredentialStore"
      credentialStoreLocation="../../src/META-INF/jps-config.xml"/>
   <sec:JaasSecurityContext
      initialContextFactoryClass="oracle.adf.share.security.
      JAASInitialContextFactory"
      jaasProviderClass="oracle.adf.share.security.providers.jps.
      JpsSecurityContext" authorizationEnforce="true"
      authenticationRequire="true"/></sec:adf-security-child>
<wpsC:adf-service-config>
   <wpsC:data-source jndi-name="java:/comp/env/jdbc/WebCenterDSDS"/>
</wpsC:adf-service-config>
<notificationC:adf-notification-config
      xmlns="http://xmlns.oracle.com/webcenter/notification/config">
   <ConnectionType>MAIL</ConnectionType>
   <ConnectionName>someMailConnection</ConnectionName>
</notificationC:adf-notification-config>
<searchC:adf-search-config
      xmlns="http://xmlns.oracle.com/webcenter/search/config">
…

50.2.3 Creating a Notifications Connection to a BPEL Server

To furnish users with the option to select mail, phone text, or Worklist messaging channels, you must configure a connection to a BPEL server (for more information, see Section 41.3.1, "Setting up Connections for Worklists"). Notifications leverages the BPEL server that is specified for the Worklist service to provide multiple messaging channels for the notifications it generates. Once a connection to a BPEL server is established, you add the following entry in the adf-config.xml file to associate the BPEL server with Notifications (Example 50-5).

Example 50-5 Configuring Notifications to Use the BPEL Server for Messaging

<notificationC:adf-notification-config
      xmlns="http://xmlns.oracle.com/webcenter/notification/config">
   <ConnectionType>BPEL</ConnectionType>
   <ConnectionName>worklistConnection</ConnectionName>
   <SenderEmailAddress>example@company.com<SenderEmailAddress>
   <SenderSMSAddress>12345</SenderSMSAddress>
</notificationC:adf-notification-config>

Where:

  • ConnectionName is the name you provided for the BPEL server when you set up that connection for the Worklist service.

  • SenderEMailAddress is a mail address from which all Notifications messages are sent. The sender mail address must match at least one driver that is configured to send messages from a corresponding domain.

  • SenderSMSAddress is the four- to six-digit number that is used by the User Messaging Server (UMS) as the driver from which all Notifications messages are sent. The sender SMS address must match at least one driver that is configured to send messages from a corresponding domain.

Example 50-6 presents a code sample, with the previous code sample in place (bold).

Example 50-6 Notifications Entries in the adf-config.xml File

<?xml version="1.0" encoding="US-ASCII" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
   xmlns:adf="http://xmlns.oracle.com/adf/config/properties"
   xmlns:sec="http://xmlns.oracle.com/adf/security/config"
   xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service"
   xmlns:jndiC="http://xmlns.oracle.com/adf/jndi/config"
   xmlns:worklistC="http://xmlns.oracle.com/webcenter/worklist/config"
   xmlns:notificationC="http://xmlns.oracle.com/webcenter/notification/config"
   xmlns:mdsC="http://xmlns.oracle.com/adf/mds/config"
   xmlns:searchC="http://xmlns.oracle.com/webcenter/search/config"
   xmlns:relC="http://xmlns.oracle.com/webcenter/relationship/config"
   xmlns:collabC="http://xmlns.oracle.com/webcenter/collab/config"
   xmlns:listC="http://xmlns.oracle.com/webcenter/list/config"
   xmlns:rcs="http://xmlns.oracle.com/adf/rcs/adf-config"
   xmlns:rcv="http://xmlns.oracle.com/adf/rcs/viewer/adf-config"xmlns:tagC=
      "http://xmlns.oracle.com/webcenter/tagging/config"
   xmlns:doclibC="http://xmlns.oracle.com/webcenter/doclib/config">
<adf:adf-properties-child xmlns="http://xmlns.oracle.com/adf/config/properties">
   <adf-property name="adfAppUID" value="ps3stage2app-7762"/>
</adf:adf-properties-child>
<sec:adf-security-child xmlns="http://xmlns.oracle.com/adf/security/config">
   <CredentialStoreContext
      credentialStoreClass="oracle.adf.share.security.providers.jps.
      CSFCredentialStore"
      credentialStoreLocation="../../src/META-INF/jps-config.xml"/>
   <sec:JaasSecurityContext
      initialContextFactoryClass="oracle.adf.share.security.
      JAASInitialContextFactory"
      jaasProviderClass="oracle.adf.share.security.providers.jps.
      JpsSecurityContext" authorizationEnforce="true"
      authenticationRequire="true"/></sec:adf-security-child>
<wpsC:adf-service-config>
   <wpsC:data-source jndi-name="java:/comp/env/jdbc/WebCenterDSDS"/>
</wpsC:adf-service-config>
<notificationC:adf-notification-config
      xmlns="http://xmlns.oracle.com/webcenter/notification/config">
   <ConnectionType>BPEL</ConnectionType>
   <ConnectionName>worklistConnection</ConnectionName>
   <SenderEmailAddress>example@company.com<SenderEmailAddress>
   <SenderSMSAddress>12345</SenderSMSAddress>
</notificationC:adf-notification-config>
<searchC:adf-search-config
      xmlns="http://xmlns.oracle.com/webcenter/search/config">
…

50.2.4 Setting Application Defaults for Notifications

This section provides information about the XML file you use to set application-level defaults for all users for Notifications. It includes the following subsections:

50.2.4.1 About Subscription Defaults

Administrator-level subscription preferences are set in a custom XML file that you create and then use to supersede the file that is provided in the notification-repository.jar for this purpose out of the box (notification-service-settings.xml). The settings in the custom XML file are analogous to the application-level subscriptions settings available to users through the Subscription Preferences task flow.

Each setting provides the following attributes:

  • id—for specifying the service ID:

    • oracle.webcenter.peopleconnections.connections, the Connections feature of the People Connections service

    • oracle.webcenter.peopleconnections.wall, the Message Board feature of the People Connections service

    • oracle.webcenter.peopleconnections.kudos, the Feedback feature of the People Connections service

  • subscription-enabled—For specifying the default value for the preference option: true or false

    Tip:

    Rather than enabling or disabling the entire subscription capability, the subscription-enabled attribute merely sets the initial state of the preference option. For example, if subscription-enabled="true", then the associated subscription option is selected by default in the Subscription Preferences task flow. If subscription-enabled="false", then the associated subscription option is not selected by default in the task flow.

  • end-user-configurable—For enabling users to change the established default or preventing users from doing so: true or false

These attributes work together to determine the initial state of the Subscription Preferences task flow.

Table 50-2 illustrates the effect of custom administrator-level subscriptions settings on the appearance of the Subscription Preferences task flow.

Table 50-2 Effect of Administrator Defaults on Subscriptions Preferences

subscription-enabledFoot 1  end-user-configurable Option in Preferences

True

True

Rendered normally, check box is selected

True

False

Grayed out, check box is selected

False

True

Rendered normally, check box is deselected

False

False

Hidden, check box is hidden

Footnote 1 Rather than enabling or disabling the entire subscription capability, the subscription-enabled attribute merely sets the initial state of the subscription.

Tip:

The most typical scenario for most notifications is False, True, rendered normally, check box is deselected.

Table 50-3 lists the types of actions that can trigger an application-level notification and associates them with their related service ID.

Table 50-3 Application-Level Activities that Can Trigger Notifications

Activity Related Service ID

A user sends you an invitation to connect

oracle.webcenter.peopleconnections.connections

A user posts a message to your Message Board

oracle.webcenter.peopleconnections.wall

A user likes your post on another user's Message Board

oracle.webcenter.peopleconnections.wall

A user comments on your post on another user's Message Board

oracle.webcenter.peopleconnections.wall

A user posts feedback for you

oracle.webcenter.peopleconnections.kudos

50.2.4.2 Setting Notifications Subscription Defaults

To set defaults for application-level Subscription preferences:

  1. Navigate to a directory with a path that contains /oracle/webcenter/notification, and create the folder custom.

    Tip:

    The directory structure can start or end with any directory or directories, as long as it has /oracle/webcenter/notification/custom in the path.

  2. In the custom folder, or in any subdirectory under /oracle/webcenter/notification/custom/, create the file notification-service-settings.xml.

  3. In the XML file, enter values for all application-level subscription options.

    Example 50-7 provides sample content for an application-wide subscription preferences setting file and an example of each required option.

    Example 50-7 Sample Subscriptions Settings XML File

    <notification-service_settings xmlns="http://xmlns.oracle.com/webcenter/notification">
 <subscription-settings>
  <service id="oracle.webcenter.peopleconnections.connections" subscription-enabled="true"
   end-user-configurable="false"/>
  <service id="oracle.webcenter.peopleconnections.wall" subscription-enabled="false"
   end-user-configurable="true"/>
  <service id="oracle.webcenter.peopleconnections.kudos" subscription-enabled="false"
   end-user-configurable="true"/>
 </subscription-settings>
</notification-service_settings>

    Note:

    If an option is not provided, the default values false/false are assigned for the service.

  4. Run the WLST command importMetadata, and import the directory content into your metadata store.

    See Also:

    For information about the importMetadata command (and other WLST commands), see the "importMetadata" section in WebLogic Scripting Tool Command Reference.

    For example:

    wls: /wc_domain/serverConfig> importMetadata(application='webcenter',
 server='serverName', fromLocation='directoryPath', docs='/**')

    Where:

    • application is the name that identifies your application

    • serverName is the name of the server on which the application is running

    • directoryPath is the directory path under which oracle/webcenter/notification/custom/<any_sub_dir_after_this>/notification-service-settings.xml is located.

      For example, if the directory path to notification-service-settings.xml is /scratch/mydir/oracle/webcenter/notification/custom, enter /scratch/mydir for directoryPath.

    • docs identifies the content to be imported, in this example, the path and files that fall under those specified for directoryPath.

Table 50-4 describes the effect of various combinations of settings for the service ID oracle.webcenter.peopleconnections.connections.

Table 50-4 Effects of Subscription Configurations for Connections

subscription-enabled end-user-configurable Effect

true

true

  • The subscribing user receives a notification message when another user sends him an invitation to connect.

  • The user can change this default.

true

false

  • The subscribing user receives a notification message when another user sends him an invitation to connect.

  • The user cannot change this default.Foot 1 

false

true

  • The subscribing user does not receive a notification message when another user sends him an invitation to connect.

  • The user can change this default.

false

false

  • The subscribing user does not receive a notification message when another user sends him an invitation to connect.

  • The option for changing this default is hidden.

Footnote 1 This is the out-of-the-box default

Table 50-5 describes the effect of various combinations of settings for the service ID oracle.webcenter.peopleconnections.wall.

Table 50-5 Effects of Subscription Configurations for Message Board

subscription-enabled end-user-configurable Effect

true

true

  • The subscribing user receives a notification message when another user posts a message on his Message board, likes his Message Board post, or comments on his Message Board post.

  • The user can change this default.

true

false

  • The subscribing user receives a notification message when another user posts a message on his Message board, likes his Message Board post, or comments on his Message Board post.

  • The user cannot change this default.

false

true

  • The subscribing user does not receive a notification message when another user posts a message on his Message board, likes his Message Board post, or comments on his Message Board post.

  • The user can change this default.

false

false

  • The subscribing user does not receive a notification message when another user posts a message on his Message board, likes his Message Board post, or comments on his Message Board post.

  • The option for changing this default is hidden.

Table 50-6 describes the effect of various combinations of settings for the service ID oracle.webcenter.peopleconnections.kudos.

Table 50-6 Effect of Subscription Configurations for Feedback

subscription-enabled end-user-configurable Effect

true

true

  • The subscribing user receives a notification message when another user leaves feedback for him.

  • The user can change this default.

true

false

  • The subscribing user receives a notification message when another user leaves feedback for him.

  • The user cannot change this default.

false

true

  • The subscribing user does not receive a notification message when another user leaves feedback for him.

  • The user can change this default.

false

false

  • The subscribing user does not receive a notification message when another user leaves feedback for him.

  • The option for changing this default is hidden.

50.2.5 Adding Notifications Task Flows to Your Application

This section provides a brief overview of Notifications task flows and describes how to add them to your application pages. It includes the following subsections:

50.2.5.1 Notifications Task flows

Notification Services exposes two task flows for managing user subscriptions:

50.2.5.2 How to Add a Notifications Task Flow to a Page

To add a Notifications task flow to a page:

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

  2. Open the page on which to add the task flow.

  3. In the Resource Palette, in the My Catalogs pane, open the WebCenter Portal - Services Catalog, then open the Task Flows folder.

  4. Drag the task flow onto a page region, then choose Region from the pop-up list.

  5. In the Confirm Add ADF Library dialog, click Add Library to add all required libraries for the component.

  6. For Subscription Preferences only, optionally, in the Edit Task Flow Binding dialog, provide a path to your input parameter map and values for the task flow's input parameters, and click OK.

    See Also:

    For information about Subscription Preferences task flow input parameters, see Section 50.2.5.3, "Subscription Preferences Task Flow Input Parameters."

    The task flow appears on the page. For example, in the Source view, you will see the content depicted in Example 50-8.

    Example 50-8 Source View Content of the Subscription Preferences Task Flow

    <af:region value="#{bindings.SubscriptionPreferences1.regionModel}" id="r1"/>

  7. In the Confirm Add Form Element dialog, click No, to avoid wrapping a form element around the task flow.

  8. Save your project, then run your page to a browser.

    The task flow appears in your browser. The options shown in the task flow are slightly different depending on whether you added the task flow to the Home portal (Figure 50-7) or a portal (Figure 50-7).

    Figure 50-7 Subscription Preferences Task Flow - Home Portal

    Description of Figure 50-7 follows
    Description of ''Figure 50-7 Subscription Preferences Task Flow - Home Portal''

    Figure 50-8 Subscription Preferences Task Flow - Portal

    Description of Figure 50-8 follows
    Description of ''Figure 50-8 Subscription Preferences Task Flow - Portal''

50.2.5.3 Subscription Preferences Task Flow Input Parameters

The Subscription Preferences task flow has input parameters that you can use to control the behavior of a given task flow instance. Table 50-7 lists and describes the input parameters associated with this task flow.

Table 50-7 Subscription Preferences Task Flow Input Parameters

Input Parameter Description

hideActions

A control for showing or hiding the Save button and Refresh icon on the task flow

  • ${true} to hide these controls

  • ${false} to show them (default)

scopeName

The name of the scope for which to set subscription preferences.

50.2.6 Setting Security for Notifications

Notifications must know the identity of a user to preserve the user's Notifications settings and to track the user's activities on subscribed services and objects. To that end, you must at least configure your application to authenticate users such that they have distinct identities for the purposes of personalization and user preferences.

For details on how to implement a basic security solution for your Portal Framework application, see Section 74.3, "Configuring ADF Security." For details on how to implement a complete security solution for your Portal Framework application, see Chapter 74, "Securing Your WebCenter Portal Framework Application."

After you configure ADF security for your application, you can open the jazn-data.xml file and modify your sample user's privileges for each task flow. To open the ADF Security Policies Editor, locate the file in the Application Resources panel and double-click its name. You can further configure grants in this view.

Note:

To successfully grant user permissions for Notifications, you must configure user permissions after deployment.

50.3 Advanced Information for Notifications

This section provides information about the APIs that are available for use with Notifications. It includes the following subsections:

50.3.1 Using Notifications Java APIs

This section provides an overview of Notifications Java APIs. It includes the following subsections:

See Also:

For detailed information about the Notifications Java APIs, see the Java API Reference for Oracle WebCenter Portal.

50.3.1.1 Configuration Settings Required to Use Notifications Java APIs

To use Notifications Java APIs, you must have the following entries in your adf-config.xml file:

<namespace path="/oracle/webcenter/page/scopedMD"
   metadata-store-usage="WebCenterFileMetadataStore"/>
<namespace path="/pageDefs" metadata-store-usage="WebCenterFileMetadataStore"/>

If these entries are not present in adf-config.xml, you can add them using your preferred text editor.

50.3.1.2 Introduction to Notifications Java APIs

Notifications Java APIs are located in the class oracle.webcenter.notification. Within the class, SubscriptionManager provides the interface for creating and managing user subscriptions using the following Java APIs:

  • FilterOption—Provides the filter criteria. Use an instance of this class while querying a user's subscriptions.

  • NotificationServiceFactory—Factory for creating and retrieving instances that correspond to Notifications interfaces. This is the entry point to the Notifications API.

  • SortOption—Defines the sort attributes for fetching subscriptions. Use an instance of this class in SubscriptionManager methods to query a user's subscriptions.

  • Subscription—Contains information about a user's subscriptions. Subscriptions for a user are created via the method that is exposed by SubscriptionManager. Instances of this class are returned by the methods exposed in SubscriptionManager.

  • SubscriptionPreference—Represents application- or scope-level subscriptions as a preference and enables setting and removing subscriptions for the corresponding service.

See Also:

For detailed information about the Notifications Java APIs, see the Java API Reference for Oracle WebCenter Portal.

50.3.1.3 How to Set up Your Application to Use Notifications Java APIs

To use the Notifications Java APIs, WebCenter Portal extension must be present in your JDeveloper application. In JDeveloper, go to the Help - About menu, and click the Extensions tab. Look for the WebCenter Portal - Notification Service, as shown in Figure 50-9. For information about adding the WebCenter Portal extension, see Chapter 2, "Setting Up Your Development Environment."

Figure 50-9 JDeveloper Extensions

Description of Figure 50-9 follows
Description of ''Figure 50-9 JDeveloper Extensions''

After confirming that Notifications is included with the WebCenter Portal extension, you must add the Notifications libraries to the project if they are not already present.

To add Notifications libraries to your project:

  1. Right-click your project and select Project Properties and then Libraries and Classpath.

  2. Click Add Library and select the WebCenter Notification Service and WebCenter Notification Service View libraries (Figure 50-10).

  3. Click OK.

    Figure 50-10 Libraries and Classpath in Project Properties

    Description of Figure 50-10 follows
    Description of ''Figure 50-10 Libraries and Classpath in Project Properties''

  4. Click OK.

50.3.2 Using Notifications Data Controls

Notifications provides a data control that enables you to create your own visualization of the subscription management functionality. This section provides an overview of the data control Notification Subscription Data Control, and lists and describes its supported methods, attributes, and classes.

See Also:

For information about using data controls in a Portal Framework application, see Section 4.1.3, "Using WebCenter Portal Data Controls."

This section includes the following subsections:

50.3.2.1 Adding a Data Control to Your Project

Add a data control to your project by right-clicking it in the Resource Palette and selecting Add to Project from the resulting context menu. Once added, you can browse the data control's methods and attributes by expanding it in the Data Controls panel in the Application Navigator.

Add a data control to an application page by dragging it onto the page from the Data Controls panel.

See Also:

For information about using data controls in a Portal Framework application, see Section 4.1.3, "Using WebCenter Portal Data Controls."

50.3.2.2 Understanding the Notification Subscription Data Control

The Notification Subscription Data Control enables you to create a custom UI that is equivalent to the Subscription Preferences and Subscription Viewer task flows should these prove insufficient for your requirements.

You can use the data control as a means of adding application-level subscription preferences. For example, if you have developed your own preferences mechanism in your application, you can use the data control to add subscription preferences to that existing mechanism rather than using the Subscription Preferences task flow directly. You can also build a custom subscription viewer UI, where all of the current user's object-level subscriptions are listed.

50.3.2.3 Notification Subscription Data Control Methods and Attributes

This section lists and describes the methods exposed in the Notification Subscription Data Control. It includes the following subsections:

50.3.2.3.1 Method: getUserSubscriptionPreferences

This method returns application-level subscription preferences for the current user.

Input Parameters

None

Return Values

Returns a collection of SubscriptionPreference objects. The SubscriptionPreference object indicates the user's preference for each service.

50.3.2.3.2 Method: getScopeSubscriptionPreferences

This method returns the scope level subscription preferences for the current user.

This method is primarily useful in a WebCenter Portal. In a Portal Framework application, it is expected that the scope will always be the default scope, that is, the application. For the default scope, this method returns application-level preferences.

Input Parameters

The input parameter scopeGuid takes a value of type String. The value specifies the GUID of the scope for which the user's scope-level preferences are returned. In a WebCenter Portal, the scope referenced here is equivalent to a portal.

Return Values

Returns a collection of SubscriptionPreference objects. Each object indicates the current user's subscription preferences for each service within the specified scope.

50.3.2.3.3 Method: saveUserSubscriptionPreferences

This method enables the application to commit and save changes to the user's application-level preferences. For example, if the user subscribes to all available services, then these changes can be committed by binding this method to the appropriate component on the UI (for example, an Apply button).

Input Parameters

None

Return Values

None

50.3.2.3.4 Method: saveScopeSubscriptionPreferences

This method enables the application to commit and save changes to the user's scope-level preferences. For example, if the user subscribes to all the available services in the given scope, then these changes can be committed and saved by binding this method to the appropriate component on the UI (for example, an Apply button).

Input Parameters

The input parameter scopeGUID takes a value of type String. The value specifies the GUID of the scope for which the modified preferences are to be saved.

Return Values

None

50.3.2.3.5 Method: getSubscriptions

The primary method for returning a list of the current user's object-level subscriptions. You can use this method to build a custom Subscription Viewer UI for showing all of a user's object-level subscriptions.

Input Parameters

Table 50-8 lists and describes the input parameters supported by this method.

Table 50-8 Input Parameters Supported by the method getSubscriptions

Input Parameter Description

FilterOption

An object that contains filter conditions for querying a user's subscriptions. FilterOption supports filtering based on portal name (WebCenter Portal only) and object name.

SortOption

An object that contains the sort or ordering condition for querying subscriptions. It supports sorting by object name, scope name (WebCenter Portal only), or the creation date of subscription.

offset

This input parameter takes an integer as a value. The offset for querying subscriptions. This is typically used while fetching the result set with pagination.

fetchSize

This input parameter takes an integer as a value. The maximum number of rows to be returned in one call.

Return Values

Returns a collection of Subscription objects matching the filter criteria and other input parameters in the order specified by the sort option.

50.3.2.3.6 Method: unsubscribe

Used to unsubscribe from, or remove, a specific subscription. This method is typically used to add the unsubscribe action to the Subscription Viewer UI, where object-level subscriptions are exposed.

Unsubscribing from a particular service at the application and portal level, or at either level, can be achieved by setting the appropriate flag in SubscriptionPreference and saving those via the appropriate save*() method listed above. The Unsubscribe method is useful within Subscription Viewer functionality.

Input Parameters

Table 50-9 lists and describes the input parameters supported by this method.

Table 50-9 Input Parameters Supported by the method Unsubscribe

Input Parameter Description

scopeGuid

Takes a value of type String. The value specifies the GUID of the scope for which the user's scope-level preferences are returned. In a WebCenter Portal, the scope referenced here is equivalent to a portal.

serviceId

The ID of the unsubscribed service

Valid service IDs include:

  • oracle.webcenter.collab.forum

  • oracle.webcenter.doclib

objectId

The GUID of the unsubscribed object.

Return Values

None

50.3.2.4 Notification Subscription Data Control Classes

The Notification Subscriptions Data Control exposes two classes as return values:

50.3.2.4.1 SubscriptionPreference

The class SubscriptionPreference represents application- or scope-level subscriptions as a preference and enables setting and removing subscriptions for the corresponding service (this is followed by a save call on the data control).

Table 50-10 lists and describes the properties associated with the SubscriptionPreference class.

Table 50-10 Properties Associated with the SubscriptionPreference Class

Property Description

hintsText

A string containing the concatenation of all the applicable activities (description) within the service that generates notifications

This is useful to display on the UI to tell the user what he is subscribing to.

serviceIcon

An icon for the service

serviceId

ID of the corresponding service

serviceName

Display name of the service

subscriptionEnabled

A flag that indicates whether the subscription is enabled

This attribute also has a setter to support the select/deselect operation on the UI.

userOverrideAllowed

A flag that indicates whether to allow the user to override the default setting

50.3.2.4.2 Subscription

The class Subscription is purely read-only and represents portal- (WebCenter Portal only) and object-level subscriptions.

Table 50-11 lists and describes the properties associated with the Subscription class.

Table 50-11 Properties Associated with the Subscription Class

Property Description

creationDate

The datetime this subscription was created

objectId

The ID of the object, if this represents an object-level subscription, otherwise null.

objectName

The name of the object, if this represents an object-level subscription, otherwise null

objectType

The object type (as defined by the corresponding service) when this subscription represents object-level subscriptions, otherwise null

scopeGuid

The GUID of the scope or portal

scopeName

The display name of the scope or portal

serviceId

The ID of the service for this subscription object

serviceName

The name of the service

userId

The ID of the user who created this subscription