19 Managing Subscriptions and Notifications

19.2.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 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 Subscription Preferences in the WebCenter Portal (for more information, see the "Subscribing to the Application, to Portals, and to Objects" chapter in Oracle Fusion Middleware Using Oracle WebCenter Portal.)

Each setting provides three 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

  • oracle.connections. community, portal membership management

• 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 WebCenter Portal's Preferences dialog. If subscription-enabled="false", then the associated subscription option is deselected by default in the dialog.

• 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 General Subscriptions tab on the Subscriptions panel in the WebCenter Portal's Preferences dialog (Figure 19-1).

Figure 19-1 General Subscriptions Tab on the Subscriptions Page

Description of "Figure 19-1 General Subscriptions Tab on the Subscriptions Page"

Table 19-1 illustrates the effect of custom administrator-level subscriptions settings on the appearance of the General Subscriptions tab.

Table 19-1 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 preference option. For example, if subscription-enabled="true", then the associated subscription option is selected by default in WebCenter Portal's Preferences. If subscription-enabled="false", then the associated subscription option is deselected by default.

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

19.2.2 Setting 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 19-1 provides sample content for an application-wide subscription preferences setting file and an example of each required option.

   Example 19-1 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"/>
     <service id="oracle.webcenter.community" subscription-enabled="true"
      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 running WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands." For information about the importMetadata() command (and other WLST commands), see the "importMetadata" section in the Oracle Fusion Middleware 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 WebCenter Portal deployment

   • serverName is the name of the server on which WebCenter Portal 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 directoryPath.

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

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

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

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

Table 19-6 describes the effect of various combinations of settings for the service ID oracle.webcenter.community.

19.2.3 Setting Subscriptions Preferences in WebCenter Portal

Individual users set their own subscription preferences in the WebCenter Portal's Preferences. Two Preferences pages are provided for this purpose:

• Subscriptions, where users subscribe to be notified about actions occurring with their portal memberships and the People Connections service (Connections, Message Board, and Feedback) and view and remove their application- and object-level subscriptions

  For more information, see the "Subscribing to the Application, to Portals, and to Objects" chapter in Oracle Fusion Middleware Using Oracle WebCenter Portal.

• Messaging, where users access controls for configuring their preferred messaging channels and filters (BPEL connection types only)

  For more information, see the "Establishing and Managing Your Messaging Channels and Filters" section in Oracle Fusion Middleware Using Oracle WebCenter Portal.

19.3.1 About Connection Channels

The Notifications connection type determines the messaging channels that are available to users when they configure their own messaging preferences for Notifications in WebCenter Portal.

Use one of two possible connection types:

• BPEL Server provides three messaging channel options to users: mail, texting (SMS), and worklist

• Mail Server delivers notification messages exclusively through a mail server that is configured for WebCenter Portal

BPEL Server

Selection of a BPEL server presupposes that you have established a connection with a BPEL server in which the User Messaging Service (UMS) is available. For information about connecting to a BPEL server, see Chapter 20, "Managing Worklists."

When WebCenter Portal has setSpacesWorkFlowConnectionName set up, the Manage Configuration button becomes available on the Messaging panel in WebCenter Portal's Preferences.

Mail Server

Selection of a mail server presupposes that you have established a connection with a mail server. Additionally, the external application associated with the mail server connection must contain shared credentials. For information about connecting to a mail server, see Chapter 15, "Managing Mail."

When Mail Server is the selected connection type, the Manage Configuration button on the Messaging panel in WebCenter Portal's Preferences might or might not be grayed-out. This depends on whether you have set up spacesWorkFlowConnection. Regardless, when Mail Server is the selected connection type and you click the Manage Configuration button for Messaging preferences opens User Messaging Preferences, any changes you make are ignored.

19.3.2 Notification Prerequisites

Before you can define a connection type for Notifications, you must take the steps and consider the information provided in the following subsections:

• Section 19.3.2.1, "Installation"

• Section 19.3.2.2, "Configuration"

• Section 19.3.2.3, "Security"

• Section 19.3.2.4, "Limitations"

19.3.3 Configuration Roadmap for Notifications

Figure 19-2 and Table 19-7 provide an overview of the prerequisites and tasks required to get the Notifications service working in WebCenter Portal applications.

Figure 19-2 Configuring the Notifications Service

Description of "Figure 19-2 Configuring the Notifications Service "

19.3.4 Specifying the Notifications Channel Using Fusion Middleware Control

To specify a Notifications message connection type with Fusion Middleware Control:

1. Log in to Oracle Fusion Middleware Control and navigate to the home page for WebCenter Portal.

   For more information, see Section 6.2, "Navigating to the Home Page for WebCenter Portal."

2. From the WebCenter Portal menu, select Settings > Application Configuration.

3. On the Application Configuration page, scroll down to Notifications (at the bottom of the page), and select a connection type to use for outbound notifications: either BPEL Server or Mail Server.

4. The next step depends on the selected connection type:

   If you select BPEL Server:

   1. From the Connection Name list, select the name you provided for the BPEL server when you set up that connection.

   2. In the Sender Mail Address field, enter 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.

   3. In the Sender SMS Address field, enter 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.

   If you select Mail Server, select a mail connection from the Connection Name list.

5. Save your changes.

6. Restart the managed server on which WebCenter Portal is deployed to make your configuration changes take effect.

19.3.5 Specifying the Notifications Channel Using WLST

Use the WLST command setNotificationsConfig to configure the connection type used for notifications. For command syntax and examples, see the "setNotificationsConfig" section in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference. See also, the "getNotificationsConfig" section in the same guide.

19.3.6 Example - Setting Up Mail Notifications for WebCenter Portal Using WLST

This section provides an example of using WLST to set up Mail Notifications for WebCenter Portal using WLST commands.

First, the example shows you how to create an external application that is configured with shared credentials, and create a mail server connection that uses the external application. Next, the example shows you how to configure WebCenter Portal to send notifications on that mail connection, and finally how to set subscription options through user preferences.

1. At the WLST command prompt, connect to the Administration Server for WebCenter Portal.

   connect('admin_user','mypassword','<servername>:7001')
   

2. Create an external application connection:

   createExtAppConnection(appName='webcenter', name='NotificationSharedApp', displayName= 'NotificationSharedApp')
   

   This command creates the connection named NotificationSharedApp.

   For more information, see the "createExtAppConnection" section in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

3. Configure shared credentials for the external application, NotificationSharedApp:

   addExtAppCredential(appName='webcenter', name='NotificationSharedApp', 
   type='SHARED', username='john.doe@example.com', password='sharedpassword')
   

   Where username refers to the email account from which email notifications will be sent. This must be in the format <user>@<domain of the mail server>.

   Optionally, you may add the following fields that will be used while sending out the mail notification.

   addExtAppField(appName='webcenter',name='NotificationSharedApp',fieldName='Email Address',fieldValue='sender's_email_address',displayToUser=false)
   addExtAppField(appName='webcenter',name='NotificationSharedApp',fieldName='Your Name',fieldValue='sender's_display_name',displayToUser=false)
   

   For more information, see the "addExtAppCredential" section in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

4. Create a Mail connection:

   createMailConnection(appName='webcenter',name='NotificationSharedConn',
            imapHost='<mailserver>',imapPort=143,
            smtpHost='<mailserver>',smtpPort=25,
            imapSecured=false,smtpSecured=false,
            appId='NotificationSharedApp',default=1)
   

   This creates a mail connection named NotificationSharedConn.

   For more information, see the "createMailConnection" section in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

5. Set Mail as the notifications channel:

      setNotificationsConfig(appName='webcenter', type='MAIL',
                             name='NotificationSharedConn')
   

   This sets NotificationSharedConn as the mail connection to use for sending notifications.

   For more information, see the "setNotificationsConfig" section in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

6. For the changes to take effect, restart the managed server on which WebCenter Portal is deployed (WC_Spaces by default).

7. Log in to WebCenter Portal, navigate to the About tab of the Profile page, and verify that your e-mail address is set in the Email field. This is to ensure that notifications are sent to the required e-mail address.

   If the e-mail address is not set, click Edit, then in the Email field, specify your e-mail address, and click Save.

8. Subscribe to the activities for which to receive notifications. For example, navigate to the Preferences page, click Subscriptions, and then select Portal Management to get notified about any membership or role changes.

9. Test your configuration by performing a subscribed activity. For example, change your role from Moderator to Participant to trigger a notification.

19.4.1 About Overwriting Default Notification Templates

You can go through MDS using WLST commands to customize the layout and content of subscription-based notification messages by overwriting the files defaultTemplate.xml and defaultTemplate_rtl.xml—when right-to-left language support is required.

You can create your own version of these xml files, editing the CSS styles for tables (label, value, background) and footers (note). You can move such tags as <payload> and <group-space-footer> to change the layout. To modify the content of these tags, you can edit the CDATA section within <html-format>.

Note that the tag <text-format/> should always be present and empty. You can use the tag <custom> to add additional content, where the enclosed <html-format> with CDATA contains the new HTML content and <text-format/> remains empty.

Example 19-2 and Example 19-3 illustrate the default content of notification message template files. You can use these to formulate your custom files.

<?xml version="1.0"?>
<notification-template xmlns="http://xmlns.oracle.com/webcenter/notification">
   <!-- The CSS Style of the Notification -->
      <style>
         <text-format/>
         <html-format>
            <![CDATA[
               <style type="text/css">
                  .title  {font-size:1.2em; font-weight:bold;
                     white-space:nowrap;}
                  .label  {text-align:right; margin-left:30px;
                     padding-right:10px; white-space:nowrap;}
                  .value  {text-align:left; margin-right:20px;
                     padding-left:10px; white-space:nowrap;
                     width:100%;}
                  .note   {font-size:0.8em; color:#999999}
                  .background {background-color:#fcfcfc}
               </style>
            ]]>
         </html-format>
      </style>


   <!-- The Subject line of the Notification -->
   <subject>
      <message-key>NOTIFICATION_SUBJECT</message-key>
   </subject>
   <group-space-subject>
      <message-key>GROUP_SPACE_SUBJECT_SUFFIX</message-key>
   </group-space-subject>
   <!-- Actual srvc-specific data. Provided/Overridden by srvc template -->
   <payload>
      <text-format/>
      <html-format/>
   </payload>


   <!-- Any generic/common footer to appear after service-specific payload -->
   <!-- Group Space footer - if applicable -->
   <group-space-footer>
      <text-format/>
      <html-format>
         <![CDATA[
            <p>
               <a href="<token>groupSpaceUrl</token>" target="_blank">
                  <message-key>GO_TO_SPACE</message-key>&nbsp;<token>
                     groupSpaceName</token>
               </a>
            </p>
         ]]>
      </html-format>
   </group-space-footer>


   <!-- Unsubscribe footers -->
   <unsubscribe-footer>
      <text-format/>
      <html-format>
         <![CDATA[
            <hr/>
            <p class="note">
               <token>unsubscribeMessage</token>
            </p>
         ]]>
      </html-format>
   </unsubscribe-footer>
</notification-template>

<?xml version="1.0"?>
<notification-template xmlns="http://xmlns.oracle.com/webcenter/notification">
   <!-- The CSS Style of the Notification -->
      <style>
         <text-format/>
         <html-format>
            <![CDATA[
               <style type="text/css">
                  .title  {font-size:1.2em; font-weight:bold;
                     white-space:nowrap;}
                  .label  {text-align:left; margin-right:30px;
                     padding-left:10px; white-space:nowrap;}
                  .value  {text-align:right; margin-left:20px;
                     padding-right:10px; white-space:nowrap;
                     width:100%;}
                  .note   {font-size:0.8em; color:#999999}
                  .background {background-color:#fcfcfc}
               </style>
            ]]>
         </html-format>
      </style>


   <!-- The Subject line of the Notification -->
   <subject>
      <message-key>NOTIFICATION_SUBJECT</message-key>
   </subject>
   <group-space-subject>
      <message-key>GROUP_SPACE_SUBJECT_SUFFIX</message-key>
   </group-space-subject>
   <!-- Actual srvc-specific data. Provided/Overridden by srvc template -->
   <payload>
      <text-format/>
      <html-format/>
   </payload>


   <!-- Any generic/common footer to appear after service-specific payload -->
   <!-- Group Space footer - if applicable -->
   <group-space-footer>
      <text-format/>
      <html-format>
         <![CDATA[
            <p>
               <a href="<token>groupSpaceUrl</token>" target="_blank">
                  <message-key>GO_TO_SPACE</message-key>&nbsp;<token>
                     groupSpaceName</token>
               </a>
            </p>
         ]]>
      </html-format>
   </group-space-footer>


   <!-- Unsubscribe footers -->
   <unsubscribe-footer>
      <text-format/>
      <html-format>
         <![CDATA[
            <hr/>
            <p class="note">
               <token>unsubscribeMessage</token>
            </p>
         ]]>
      </html-format>
   </unsubscribe-footer>
</notification-template>

19.4.2 Overwriting a Default Notifications Template

To overwrite an existing xml file to customize notification message formats:

1. Create a custom XML file with the name defaultTemplate.xml (or defaultTemplate_rtl.xml, for right-to-left language template).

2. Populate the custom file with your revised version of one of these default files.

   See Also:

   Example 19-2 and Example 19-3 show default file content.

3. Overwrite the original file, placing the custom file where the absolute path to the file contains the namespace oracle/webcenter/notification/custom.

   For example:

   /tmp/repository/oracle/webcenter/notification/custom/template/defaultTemplate.xml
   

4. Upload the custom file into WebCenter Portal's MDS repository by running the importMetadata() WLST command.

   For example:

   importMetadata(application='webcenter', server='WC_Spaces',
      fromLocation='template-file-location',
      docs='/oracle/webcenter/notification/custom/template/defaultTemplate.xml')
   

   The template-file-location points to the directory under which the fully qualified custom file is located. The fully qualified custom file is typically placed under the directory structure equivalent to its namespace. For example, consider a file that is created under the following namespace:

   /tmp/repository/oracle/webcenter/notification/custom/template/defaultTemplate.xml
   

   In such a case, the fromLocation is /tmp/repository because the remaining sub-directory consists of the namespace for the XML file. The namespace must have at least the path /oracle/webcenter/notification/custom.

   See Also:

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

5. Restart WebCenter Portal.